💫 Toolkit to help you get started with SDD or any other process!
feat(extensions): select exact catalog releases (#4726)
Dorid2ddd910266a
diff --git a/docs/reference/extensions.md b/docs/reference/extensions.mdindex 81c5ad3ff..8d9eaaada 100644--- a/docs/reference/extensions.md+++ b/docs/reference/extensions.md@@ -26,6 +26,7 @@ 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) |@@ -33,6 +34,13 @@ Installs an extension from the catalog, a URL, or a local directory. Extension cIf a generic integration refresh cannot produce every extension invocation (for example, because a command or skill is user-modified or its source is missing), it warns and restores that extension's prior registered artifacts. Other extensions can still refresh.+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@@ -81,9 +89,47 @@ including for help, the existing human-readable behavior is unchanged.```bashspecify 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.+Equivalent PEP 440 version spellings (for example, `v1.0` and `1.0`) select+the same release; the catalog's advertised spelling remains visible.++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.+As with current releases, a digest may use a case-insensitive `sha256:` prefix+and surrounding whitespace.++```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 Extensionsdiff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.pyindex f46328c14..6242dc2c0 100644--- a/src/specify_cli/extensions/__init__.py+++ b/src/specify_cli/extensions/__init__.py@@ -3234,6 +3234,8 @@ class ExtensionManager: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.@@ -3283,6 +3285,26 @@ class ExtensionManager: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:+ try:+ version_matches = pkg_version.Version(+ archive_manifest.version+ ) == pkg_version.Version(expected_version)+ except pkg_version.InvalidVersion:+ version_matches = False+ if not version_matches:+ raise ValidationError(+ f"Downloaded extension '{archive_manifest.id}' declares version "+ f"{archive_manifest.version}, expected {expected_version}."+ )+# Install from extracted directoryreturn self.install_from_directory(extension_dir,@@ -3446,6 +3468,8 @@ class ExtensionManager: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(@@ -3457,6 +3481,8 @@ class ExtensionManager: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:@@ -5032,13 +5058,16 @@ class ExtensionCatalog(CatalogStackBase):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 releaseReturns:Extension metadata (annotated with ``_catalog_name`` and@@ -5047,9 +5076,20 @@ class ExtensionCatalog(CatalogStackBase):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:@@ -5065,13 +5105,30 @@ class ExtensionCatalog(CatalogStackBase):Raises:ExtensionError: If extension not found or download fails"""- import urllib.error-# Get extension info from catalogext_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 locallyif ext_info.get("bundled") and not ext_info.get("download_url"):raise ExtensionError(diff --git a/src/specify_cli/extensions/_catalog_versions.py b/src/specify_cli/extensions/_catalog_versions.pynew file mode 100644index 000000000..63965cbee--- /dev/null+++ b/src/specify_cli/extensions/_catalog_versions.py@@ -0,0 +1,153 @@+"""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."+ )+ digest = record.get("sha256")+ if isinstance(digest, str):+ digest = digest.strip()+ if digest[:7].lower() == "sha256:":+ digest = digest[7:].strip()+ if not isinstance(digest, str) or not _SHA256.fullmatch(digest):+ 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)+ current = entry.get("version")+ if version is None or version == current:+ return entry+ try:+ requested = Version(version)+ except InvalidVersion:+ return None+ if isinstance(current, str):+ try:+ if requested == Version(current):+ return entry+ except InvalidVersion:+ # Legacy entries without history are still selectable by exact+ # spelling above, even if their version is not PEP 440 compliant.+ pass+ for advertised, record in releases.items():+ if requested == Version(advertised):+ common = {+ key: value for key, value in entry.items() if key not in _CURRENT_ONLY+ }+ return {**common, **record, "version": advertised}+ return None+++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)]diff --git a/src/specify_cli/extensions/command_add.py b/src/specify_cli/extensions/command_add.pyindex 9a5bd7cad..30a4ff717 100644--- a/src/specify_cli/extensions/command_add.py+++ b/src/specify_cli/extensions/command_add.py@@ -9,6 +9,7 @@ from pathlib import Pathfrom typing import Optionalimport typer+from packaging.version import InvalidVersion, Versionfrom rich.markup import escape as _escape_markupfrom rich.panel import Panel@@ -23,15 +24,24 @@ def extension_add(from_url: Optional[str] = typer.Option(None, "--from", help="Install from custom URL"),force: bool = typer.Option(False, "--force", help="Overwrite if already installed"),priority: int = typer.Option(10, "--priority", help="Resolution priority (lower = higher precedence, default 10)"),+ version: Optional[str] = typer.Option(None, "--version", help="Install an exact version from a catalog"),):"""Install an extension."""from . import ExtensionManager, ExtensionCatalog, ExtensionError, ValidationError, CompatibilityError, REINSTALL_COMMAND+ # Compatibility callers invoke this function directly, in which case+ # Typer supplies its OptionInfo object instead of a parsed option value.+ if not isinstance(version, str):+ version = None+project_root = _commands._require_specify_project()# Validate priorityif priority < 1:console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")raise typer.Exit(1)+ if version is not None and (not version.strip() or dev or from_url):+ console.print("[red]Error:[/red] --version requires a catalog install (without --dev or --from).")+ raise typer.Exit(1)manager = ExtensionManager(project_root)speckit_version = _commands.get_speckit_version()@@ -133,7 +143,10 @@ def extension_add(else:# Try bundled extensions first (shipped with spec-kit)- bundled_path = _commands._locate_bundled_extension(extension)+ bundled_path = (+ _commands._locate_bundled_extension(extension)+ if version is None else None+ )if bundled_path is not None:manifest = manager.install_from_directory(bundled_path, speckit_version, priority=priority, force=force@@ -155,9 +168,55 @@ def extension_add(console.print(" specify extension search")raise typer.Exit(1)+ if version is not None:+ # Resolve within the winning catalog source. A missing+ # historical release must not fall through to a lower+ # priority (or discovery-only) catalog. Reuse the entry+ # already resolved above rather than fetching again.+ from ._catalog_versions import select_release++ selected = select_release(ext_info, version)+ if selected is None:+ console.print(+ f"[red]Error:[/red] Extension '{_escape_markup(str(ext_info['id']))}' "+ f"has no catalog release for version {_escape_markup(version)}."+ )+ raise typer.Exit(1)+ ext_info = selected+ if not ext_info.get("_install_allowed", True):+ console.print(+ f"[red]Error:[/red] Extension '{_escape_markup(str(ext_info['id']))}' "+ "is from a discovery-only catalog and cannot be installed."+ )+ raise typer.Exit(1)+# If catalog resolved a display name to an ID, check bundled againresolved_id = ext_info['id']- if resolved_id != extension:+ if version is not None and ext_info.get("bundled") and not ext_info.get("download_url"):+ from . import ExtensionManifest++ candidate = _commands._locate_bundled_extension(resolved_id)+ if candidate is not None:+ bundled_manifest = ExtensionManifest(candidate / "extension.yml")+ try:+ packaged_matches = Version(bundled_manifest.version) == Version(+ version+ )+ except InvalidVersion:+ packaged_matches = False+ if packaged_matches:+ bundled_path = candidate+ manifest = manager.install_from_directory(+ bundled_path, speckit_version, priority=priority, force=force+ )+ if bundled_path is None:+ console.print(+ f"[red]Error:[/red] Bundled extension '{_escape_markup(resolved_id)}' "+ f"version {_escape_markup(version)} is not shipped with this Spec Kit release. "+ "Upgrade Spec Kit or choose an available catalog archive."+ )+ raise typer.Exit(1)+ if version is None and resolved_id != extension:bundled_path = _commands._locate_bundled_extension(resolved_id)if bundled_path is not None:manifest = manager.install_from_directory(@@ -206,7 +265,11 @@ def extension_add(# Download extension archive (use the resolved catalog ID).extension_id = ext_info['id']console.print(f"Downloading {_escape_markup(str(ext_info['name']))} v{_escape_markup(str(ext_info.get('version', 'unknown')))}...")- archive_path = catalog.download_extension(extension_id)+ archive_path = (+ catalog.download_extension_info(ext_info)+ if version is not None+ else catalog.download_extension(extension_id)+ )try:manifest = manager.install_from_zip(@@ -215,6 +278,10 @@ def extension_add(priority=priority,force=force,catalog_name=ext_info.get("_catalog_name"),+ **(+ {"expected_id": extension_id, "expected_version": version}+ if version is not None else {}+ ),)finally:archive_path.unlink(missing_ok=True)diff --git a/src/specify_cli/extensions/command_info.py b/src/specify_cli/extensions/command_info.pyindex a4c68c7a9..d1acd599a 100644--- a/src/specify_cli/extensions/command_info.py+++ b/src/specify_cli/extensions/command_info.py@@ -14,9 +14,10 @@ from . import _commands@_commands.extension_app.command("info")def extension_info(extension: str = typer.Argument(help="Extension ID or name"),+ versions: bool = typer.Option(False, "--versions", help="List catalog versions"),):"""Show detailed information about an extension."""- from . import ExtensionCatalog, ExtensionManager, normalize_priority+ from . import ExtensionCatalog, ExtensionManager, ExtensionError, normalize_priorityproject_root = _commands._require_specify_project()catalog = ExtensionCatalog(project_root)@@ -36,12 +37,43 @@ def extension_info(ext_info, catalog_error = _commands._resolve_catalog_extension(lookup_key, catalog, "info")+ # Direct compatibility callers receive Typer's OptionInfo default rather+ # than a parsed bool; only the CLI's explicit True enables this view.+ show_versions = versions is True# Case 1: Found in catalog - show full catalog infoif ext_info:+ if show_versions:+ try:+ from ._catalog_versions import available_versions++ available = available_versions(ext_info)+ except ExtensionError as exc:+ _commands.console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")+ raise typer.Exit(1) from exc+ _commands.console.print(+ f"Catalog versions for {_escape_markup(str(ext_info['id']))}:"+ )+ for index, available_version in enumerate(available):+ current = " (current)" if index == 0 else ""+ _commands.console.print(f" {_escape_markup(available_version)}{current}")+ if not ext_info.get("_install_allowed", True):+ _commands.console.print("[yellow]Discovery only; catalog installation is disabled.[/yellow]")+ return_print_extension_info(ext_info, manager)return+ if show_versions:+ if catalog_error:+ _commands.console.print(+ f"[red]Error:[/red] Could not query extension catalog: {_escape_markup(str(catalog_error))}"+ )+ raise typer.Exit(1)+ _commands.console.print(+ f"[red]Error:[/red] No catalog versions found for {_escape_markup(extension)}."+ )+ raise typer.Exit(1)+# Case 2: Installed locally but catalog lookup failed or not in catalogif resolved_installed_id:# Get local manifest infodiff --git a/tests/specify_cli/extensions/test_catalog_versions.py b/tests/specify_cli/extensions/test_catalog_versions.pynew file mode 100644index 000000000..404256baa--- /dev/null+++ b/tests/specify_cli/extensions/test_catalog_versions.py@@ -0,0 +1,639 @@+"""Regression coverage for exact releases in an extension catalog (#4719)."""++from __future__ import annotations++import hashlib+import zipfile+from io import BytesIO+from pathlib import Path++import pytest+import yaml+from typer.testing import CliRunner++from specify_cli import app+from specify_cli.extensions import (+ CatalogEntry,+ ExtensionCatalog,+ ExtensionError,+ ExtensionManifest,+)+++def _archive(tmp_path: Path, version: str, extension_id: str = "demo-history") -> Path:+ path = tmp_path / f"{extension_id}-{version}.zip"+ manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": extension_id,+ "name": "Demo History",+ "version": version,+ "description": "Historical release test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {"name": "speckit.demo-history.hello", "file": "commands/hello.md"}+ ]+ },+ }+ with zipfile.ZipFile(path, "w") as archive:+ archive.writestr("extension.yml", yaml.safe_dump(manifest))+ archive.writestr("commands/hello.md", "---\ndescription: hello\n---\n\nhi\n")+ return path+++def _entry(old_archive: Path) -> dict:+ return {+ "id": "demo-history",+ "name": "Demo History",+ "description": "Current description",+ "version": "0.5.1",+ "download_url": "https://example.com/demo-0.5.1.zip",+ "sha256": "a" * 64,+ "requires": {"speckit_version": ">=1.0.0"},+ "provides": {"commands": 3},+ "_catalog_name": "trusted",+ "_install_allowed": True,+ "releases": {+ "0.4.12": {+ "download_url": "https://example.com/demo-0.4.12.zip",+ "sha256": hashlib.sha256(old_archive.read_bytes()).hexdigest(),+ "requires": {"speckit_version": ">=0.1.0"},+ }+ },+ }+++def _catalog(+ monkeypatch: pytest.MonkeyPatch, project: Path, entry: dict+) -> ExtensionCatalog:+ monkeypatch.setattr(+ ExtensionCatalog, "_get_merged_extensions", lambda self: [entry]+ )+ return ExtensionCatalog(project)+++class _ArchiveResponse(BytesIO):+ def __init__(self, data: bytes, url: str):+ super().__init__(data)+ self.url = url++ def geturl(self):+ return self.url++ def getheader(self, _name):+ return "application/zip"+++def test_legacy_entry_still_selects_its_current_release(tmp_path, monkeypatch):+ entry = {+ "id": "legacy",+ "version": "1.0.0",+ "download_url": "https://example.com/a.zip",+ }+ catalog = _catalog(monkeypatch, tmp_path, entry)++ assert catalog.get_extension_info("legacy") == entry+ assert catalog.get_extension_info("legacy", "1.0.0") == entry+ assert catalog.get_extension_info("legacy", "v1.0") == entry+ assert catalog.get_extension_info("legacy", "0.9.0") is None+ assert catalog.get_extension_versions("legacy") == ["1.0.0"]+++def test_historical_release_selects_its_own_url_digest_and_requirements(+ tmp_path, monkeypatch+):+ entry = _entry(_archive(tmp_path, "0.4.12"))+ catalog = _catalog(monkeypatch, tmp_path, entry)++ current = catalog.get_extension_info("demo-history")+ old = catalog.get_extension_info("demo-history", "0.4.12")++ assert current["download_url"].endswith("0.5.1.zip")+ assert old["download_url"].endswith("0.4.12.zip")+ assert old["version"] == "0.4.12"+ assert old["sha256"] != current["sha256"]+ assert old["requires"] == {"speckit_version": ">=0.1.0"}+ assert "provides" not in old+ assert old["_catalog_name"] == "trusted"+ assert "releases" not in old+ assert catalog.get_extension_info("demo-history", "0.3.0") is None+ assert catalog.get_extension_versions("demo-history") == ["0.5.1", "0.4.12"]+++def test_equivalent_version_spelling_preserves_advertised_release(+ tmp_path, monkeypatch+):+ entry = _entry(_archive(tmp_path, "0.4.12"))+ catalog = _catalog(monkeypatch, tmp_path, entry)++ assert catalog.get_extension_info("demo-history", "v0.5.1") == entry+ historical = catalog.get_extension_info("demo-history", "0.4.12.0")+ assert historical["version"] == "0.4.12"+ assert historical["download_url"] == entry["releases"]["0.4.12"]["download_url"]+ assert catalog.get_extension_info("demo-history", "not-a-version") is None+++def test_requested_version_does_not_fall_through_to_lower_priority_catalog(+ tmp_path, monkeypatch+):+ old_archive = _archive(tmp_path, "0.4.12")+ high = _entry(old_archive)+ high["releases"] = {}+ low = _entry(old_archive)+ catalog = ExtensionCatalog(tmp_path)+ sources = [+ CatalogEntry("https://example.com/high.json", "high", 1, True),+ CatalogEntry("https://example.com/low.json", "low", 2, True),+ ]+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: sources)+ monkeypatch.setattr(+ catalog,+ "_fetch_single_catalog",+ lambda source, _force=False: {+ "schema_version": "1.0",+ "extensions": {"demo-history": high if source.name == "high" else low},+ },+ )++ assert catalog.get_extension_info("demo-history", "0.4.12") is None+ assert catalog.get_extension_versions("demo-history") == ["0.5.1"]++[email protected]("second_lookup", ["lower_priority", "unavailable"])+def test_exact_cli_install_uses_first_resolved_catalog_snapshot(+ tmp_path, monkeypatch, second_lookup+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ high = _entry(old_archive)+ low = _entry(old_archive)+ low["releases"]["0.4.12"]["download_url"] = "https://example.com/low.zip"+ fetches = []+ selected = []++ def merged(_self):+ fetches.append(True)+ if len(fetches) == 1:+ return [high]+ if second_lookup == "unavailable":+ raise ExtensionError("winning catalog is unavailable")+ return [low]++ def download(_self, info):+ selected.append(info)+ return old_archive++ monkeypatch.setattr(ExtensionCatalog, "_get_merged_extensions", merged)+ monkeypatch.setattr(ExtensionCatalog, "download_extension_info", download)+ monkeypatch.chdir(project)++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.4.12"]+ )++ assert result.exit_code == 0, result.output+ assert len(fetches) == 1+ assert selected[0]["download_url"] == "https://example.com/demo-0.4.12.zip"+++ "bad_history",+ [+ [],+ None,+ {+ "not-a-version": {+ "download_url": "https://example.com/a.zip",+ "sha256": "a" * 64,+ }+ },+ {"0.5.1": {"download_url": "https://example.com/a.zip", "sha256": "a" * 64}},+ {"0.5.1.0": {"download_url": "https://example.com/a.zip", "sha256": "a" * 64}},+ {"0.4.12": {"download_url": "https://example.com/a.zip"}},+ {+ "0.4.12": {+ "download_url": "https://example.com/a.zip",+ "sha256": "md5:" + "a" * 64,+ }+ },+ {+ "0.4.12": {+ "download_url": "https://example.com/a.zip",+ "sha256": "a" * 64,+ "id": "other",+ }+ },+ ],+)+def test_malformed_history_is_rejected(tmp_path, monkeypatch, bad_history):+ entry = {"id": "demo-history", "version": "0.5.1", "releases": bad_history}+ catalog = _catalog(monkeypatch, tmp_path, entry)+ with pytest.raises(ExtensionError):+ catalog.get_extension_info("demo-history", "0.4.12")+++def test_selected_release_download_uses_its_url_without_relookup(tmp_path, monkeypatch):+ archive = _archive(tmp_path, "0.4.12")+ entry = _entry(archive)+ catalog = _catalog(monkeypatch, tmp_path, entry)+ selected = catalog.get_extension_info("demo-history", "0.4.12")+ requested = []++ def open_url(url, **_kwargs):+ requested.append(url)+ return _ArchiveResponse(archive.read_bytes(), url)++ monkeypatch.setattr(catalog, "_open_url", open_url)+ monkeypatch.setattr(+ catalog,+ "get_extension_info",+ lambda *_args: pytest.fail("unexpected second lookup"),+ )+ downloaded = catalog.download_extension_info(+ selected, target_dir=tmp_path / "downloads"+ )++ assert requested == ["https://example.com/demo-0.4.12.zip"]+ assert downloaded.read_bytes() == archive.read_bytes()+++def test_historical_release_accepts_prefixed_digest(tmp_path, monkeypatch):+ archive = _archive(tmp_path, "0.4.12")+ entry = _entry(archive)+ digest = entry["releases"]["0.4.12"]["sha256"]+ entry["releases"]["0.4.12"]["sha256"] = f" SHA256: {digest.upper()} "+ catalog = _catalog(monkeypatch, tmp_path, entry)+ selected = catalog.get_extension_info("demo-history", "0.4.12")++ monkeypatch.setattr(+ catalog,+ "_open_url",+ lambda url, **_kwargs: _ArchiveResponse(archive.read_bytes(), url),+ )+ downloaded = catalog.download_extension_info(+ selected, target_dir=tmp_path / "downloads"+ )++ assert selected["sha256"] == f" SHA256: {digest.upper()} "+ assert downloaded.read_bytes() == archive.read_bytes()+++def test_selected_discovery_release_cannot_be_downloaded(tmp_path, monkeypatch):+ entry = _entry(_archive(tmp_path, "0.4.12"))+ entry["_install_allowed"] = False+ catalog = _catalog(monkeypatch, tmp_path, entry)+ selected = catalog.get_extension_info("demo-history", "0.4.12")++ with pytest.raises(ExtensionError, match="discovery-only"):+ catalog.download_extension_info(selected)+++def test_exact_cli_install_rejects_wrong_archive_before_writing(tmp_path, monkeypatch):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ new_archive = _archive(tmp_path, "0.5.1")+ _catalog(monkeypatch, project, _entry(old_archive))+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog, "download_extension_info", lambda self, _info: new_archive+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.4.12"]+ )++ assert result.exit_code == 1+ assert "declares version 0.5.1, expected 0.4.12" in " ".join(result.output.split())+ assert not (+ project / ".specify" / "extensions" / "demo-history" / "extension.yml"+ ).exists()+++def test_exact_cli_install_reports_invalid_legacy_catalog_version(+ tmp_path, monkeypatch+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ archive = _archive(tmp_path, "0.4.12")+ entry = _entry(archive)+ entry["version"] = "legacy-current"+ del entry["releases"]+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog, "download_extension_info", lambda self, _info: archive+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "legacy-current"]+ )++ assert result.exit_code == 1+ assert "Validation Error" in result.output+ assert "declares version 0.4.12, expected legacy-current" in " ".join(+ result.output.split()+ )+ assert not (project / ".specify" / "extensions" / "demo-history").exists()+++def test_exact_cli_install_rejects_wrong_archive_id_before_writing(+ tmp_path, monkeypatch+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ wrong_id_archive = _archive(tmp_path, "0.4.12", "another-extension")+ _catalog(monkeypatch, project, _entry(old_archive))+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog,+ "download_extension_info",+ lambda self, _info: wrong_id_archive,+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.4.12"]+ )++ assert result.exit_code == 1+ assert "declares ID 'another-extension', expected 'demo-history'" in " ".join(+ result.output.split()+ )+ assert not (project / ".specify" / "extensions" / "another-extension").exists()+ assert not (project / ".specify" / "extensions" / "demo-history").exists()+++def test_exact_cli_install_rejects_wrong_historical_digest_before_writing(+ tmp_path, monkeypatch+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ entry = _entry(old_archive)+ entry["releases"]["0.4.12"]["sha256"] = "0" * 64+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)+ requested = []++ def open_url(self, url, **_kwargs):+ requested.append(url)+ return _ArchiveResponse(old_archive.read_bytes(), url)++ monkeypatch.setattr(ExtensionCatalog, "_open_url", open_url)++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.4.12"]+ )++ assert result.exit_code == 1+ assert requested == ["https://example.com/demo-0.4.12.zip"]+ assert "Integrity check failed for 'demo-history'" in " ".join(+ result.output.split()+ )+ assert not (project / ".specify" / "extensions" / "demo-history").exists()+++def test_unqualified_cli_install_uses_current_release_with_history(+ tmp_path, monkeypatch+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ current_archive = _archive(tmp_path, "0.5.1")+ entry = _entry(old_archive)+ entry["sha256"] = hashlib.sha256(current_archive.read_bytes()).hexdigest()+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)+ requested = []++ def open_url(self, url, **_kwargs):+ requested.append(url)+ return _ArchiveResponse(current_archive.read_bytes(), url)++ monkeypatch.setattr(ExtensionCatalog, "_open_url", open_url)++ result = CliRunner().invoke(app, ["extension", "add", "demo-history"])++ assert result.exit_code == 0, result.output+ assert requested == ["https://example.com/demo-0.5.1.zip"]+ installed = yaml.safe_load(+ (+ project / ".specify" / "extensions" / "demo-history" / "extension.yml"+ ).read_text(encoding="utf-8")+ )+ assert installed["extension"]["version"] == "0.5.1"++[email protected]("requested_version", ["0.4.12", "v0.4.12"])+def test_exact_cli_install_historical_release(tmp_path, monkeypatch, requested_version):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ old_archive = _archive(tmp_path, "0.4.12")+ _catalog(monkeypatch, project, _entry(old_archive))+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog, "download_extension_info", lambda self, _info: old_archive+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", requested_version]+ )++ assert result.exit_code == 0, result.output+ installed = yaml.safe_load(+ (+ project / ".specify" / "extensions" / "demo-history" / "extension.yml"+ ).read_text(encoding="utf-8")+ )+ assert installed["extension"]["version"] == "0.4.12"+++def test_info_lists_versions_and_discovery_only_policy(tmp_path, monkeypatch):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ entry = _entry(_archive(tmp_path, "0.4.12"))+ entry["_install_allowed"] = False+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)++ result = CliRunner().invoke(+ app, ["extension", "info", "demo-history", "--versions"]+ )++ assert result.exit_code == 0, result.output+ assert "0.5.1 (current)" in result.output+ assert "0.4.12" in result.output+ assert "Discovery only" in result.output+++def test_info_versions_uses_first_resolved_catalog_snapshot(tmp_path, monkeypatch):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ high = _entry(_archive(tmp_path, "0.4.12"))+ low = _entry(_archive(tmp_path, "0.4.12"))+ low["version"] = "0.8.0"+ fetches = []++ def merged(_self):+ fetches.append(True)+ return [high if len(fetches) == 1 else low]++ monkeypatch.setattr(ExtensionCatalog, "_get_merged_extensions", merged)+ monkeypatch.chdir(project)++ result = CliRunner().invoke(+ app, ["extension", "info", "demo-history", "--versions"]+ )++ assert result.exit_code == 0, result.output+ assert len(fetches) == 1+ assert "0.5.1 (current)" in result.output+ assert "0.8.0" not in result.output+++def test_info_versions_preserves_catalog_failure(tmp_path, monkeypatch):+ from specify_cli.extensions import _commands++ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ _commands,+ "_resolve_catalog_extension",+ lambda *_args: (None, ExtensionError("catalog fetch failed")),+ )++ result = CliRunner().invoke(+ app, ["extension", "info", "demo-history", "--versions"]+ )++ assert result.exit_code == 1+ assert "Could not query extension catalog: catalog fetch failed" in " ".join(+ result.output.split()+ )+ assert "No catalog versions found" not in result.output+++def test_exact_cli_install_rejects_missing_version_in_winning_catalog(+ tmp_path, monkeypatch+):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ _catalog(monkeypatch, project, _entry(_archive(tmp_path, "0.4.12")))+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog,+ "download_extension_info",+ lambda *_args: pytest.fail("must not download a different version"),+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.3.0"]+ )++ assert result.exit_code == 1+ assert "no catalog release for version 0.3.0" in " ".join(result.output.split())+++def test_exact_cli_install_refuses_discovery_only_catalog(tmp_path, monkeypatch):+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ entry = _entry(_archive(tmp_path, "0.4.12"))+ entry["_install_allowed"] = False+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)+ monkeypatch.setattr(+ ExtensionCatalog,+ "download_extension_info",+ lambda *_args: pytest.fail("discovery-only catalogs must not download"),+ )++ result = CliRunner().invoke(+ app, ["extension", "add", "demo-history", "--version", "0.4.12"]+ )++ assert result.exit_code == 1+ assert "discovery-only" in result.output+++def test_exact_cli_does_not_bypass_discovery_policy_via_bundled_copy(+ tmp_path, monkeypatch+):+ from specify_cli._assets import _locate_bundled_extension++ bundled = _locate_bundled_extension("agent-context")+ assert bundled is not None+ version = ExtensionManifest(bundled / "extension.yml").version+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ entry = {+ "id": "agent-context",+ "name": "Agent Context",+ "version": version,+ "bundled": True,+ "_catalog_name": "discovery",+ "_install_allowed": False,+ }+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)++ result = CliRunner().invoke(+ app, ["extension", "add", "agent-context", "--version", version]+ )++ assert result.exit_code == 1+ assert "discovery-only" in result.output+ assert not (+ project / ".specify" / "extensions" / "agent-context" / "extension.yml"+ ).exists()++[email protected]("version_case", ["exact", "equivalent", "mismatch"])+def test_exact_cli_bundled_version_must_match_packaged_manifest(+ tmp_path, monkeypatch, version_case+):+ from specify_cli._assets import _locate_bundled_extension++ bundled = _locate_bundled_extension("agent-context")+ assert bundled is not None+ packaged_version = ExtensionManifest(bundled / "extension.yml").version+ requested_version = {+ "exact": packaged_version,+ "equivalent": f"v{packaged_version}",+ "mismatch": "9999.0.0",+ }[version_case]+ project = tmp_path / "project"+ (project / ".specify").mkdir(parents=True)+ entry = {+ "id": "agent-context",+ "name": "Agent Context",+ "version": requested_version+ if version_case == "mismatch"+ else packaged_version,+ "bundled": True,+ "_catalog_name": "trusted",+ "_install_allowed": True,+ }+ _catalog(monkeypatch, project, entry)+ monkeypatch.chdir(project)++ result = CliRunner().invoke(+ app, ["extension", "add", "agent-context", "--version", requested_version]+ )++ installed_manifest = (+ project / ".specify" / "extensions" / "agent-context" / "extension.yml"+ )+ if version_case != "mismatch":+ assert result.exit_code == 0, result.output+ assert ExtensionManifest(installed_manifest).version == packaged_version+ else:+ assert result.exit_code == 1+ assert f"version {requested_version} is not shipped" in " ".join(+ result.output.split()+ )+ assert not installed_manifest.exists()