Skip to content

💫 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.md
index 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 c
If 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.
```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.
+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 Extensions
diff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.py
index 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 directory
return 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 release
Returns:
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 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(
diff --git a/src/specify_cli/extensions/_catalog_versions.py b/src/specify_cli/extensions/_catalog_versions.py
new file mode 100644
index 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.py
index 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 Path
from typing import Optional
import typer
+from packaging.version import InvalidVersion, Version
from rich.markup import escape as _escape_markup
from 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 priority
if 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 again
resolved_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.py
index 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_priority
project_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 info
if 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 catalog
if resolved_installed_id:
# Get local manifest info
diff --git a/tests/specify_cli/extensions/test_catalog_versions.py b/tests/specify_cli/extensions/test_catalog_versions.py
new file mode 100644
index 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()