💫 Toolkit to help you get started with SDD or any other process!
feat(workflows): select exact step catalog releases (#4840)
Manfred Riem2dda047809dd
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex 84b492087..b99fbea42 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -664,6 +664,54 @@ Catalog installs resolve individual file URLs from the active step catalogs andthen go through the same validation and commit path as `--dev` and `--from`.Discovery-only catalogs cannot be installed from.+##### Catalog release history++`specify workflow step info <id> --versions` lists the current and historical+releases in the winning catalog. `specify workflow step add <id> --version <v>`+selects the exact catalog release; without `--version`, `add` installs the+advertised current release. The requested version never falls back to a+lower-priority catalog, and discovery-only sources remain non-installable.+`--version` cannot be combined with direct `--dev` or `--from` installs.++Existing single-version catalog entries continue to work. Keep the current+release's `version`, `step_yml_url` (or `url`), `init_url`, and optional files+at the top level. An optional `releases` mapping adds historical versions:++```json+{+ "steps": {+ "my-step": {+ "version": "2.0",+ "step_yml_url": "https://example.com/my-step/2.0/step.yml",+ "releases": {+ "1.0": {+ "step_yml_url": "https://example.com/my-step/1.0/step.yml",+ "init_url": "https://example.com/my-step/1.0/__init__.py",+ "extra_files": {"helper.py": "https://example.com/my-step/1.0/helper.py"},+ "sha256": {+ "step.yml": "<64 hex digits>",+ "__init__.py": "<64 hex digits>",+ "helper.py": "<64 hex digits>"+ }+ }+ }+ }+ }+}+```++Each historical release must supply its own step URL and SHA-256 digest for+every downloaded file. `init_url` can be omitted when derived from a+`step_yml_url` ending in `step.yml`. To select the current version explicitly,+its top-level entry must likewise supply the per-file `sha256` mapping.+Release-specific files and requirements are not inherited from the current+release. Repeated or malformed versions are rejected; equivalent PEP 440+spellings such as `v1.0` and `1.0` select the same advertised release. The+downloaded `step.yml` must declare the selected step ID and version. An+unqualified legacy catalog install does not require digests or a step version.+Only one version of each step ID can be installed at a time; use `--force` to+replace a previous installation after reviewing the selected package.+#### Replacement and force```bashdiff --git a/src/specify_cli/workflows/step/catalog/_domain.py b/src/specify_cli/workflows/step/catalog/_domain.pyindex bc166562b..d1f9ecf75 100644--- a/src/specify_cli/workflows/step/catalog/_domain.py+++ b/src/specify_cli/workflows/step/catalog/_domain.py@@ -40,6 +40,19 @@ class StepValidationError(StepCatalogError):"""Validation error for step catalog config or step data."""+class _DuplicateCatalogField(StepCatalogError):+ """An ambiguous JSON object in a step catalog."""+++def _unique_json_fields(pairs: list[tuple[str, Any]]) -> dict[str, Any]:+ result: dict[str, Any] = {}+ for key, value in pairs:+ if key in result:+ raise _DuplicateCatalogField(f"Duplicate field '{key}' in step catalog.")+ result[key] = value+ return result++# ---------------------------------------------------------------------------# StepCatalogEntry# ---------------------------------------------------------------------------@@ -470,9 +483,11 @@ class StepCatalog:if cache_safe and not force_refresh and self._is_url_cache_valid(entry.url):try:with open(cache_file, encoding="utf-8") as f:- cached = json.load(f)+ cached = json.load(f, object_pairs_hook=_unique_json_fields)if isinstance(cached, dict):return cached+ except _DuplicateCatalogField:+ raiseexcept (UnicodeDecodeError, json.JSONDecodeError, OSError):# Ignore invalid/unreadable cache and fall back to fetching from source.pass@@ -530,15 +545,20 @@ class StepCatalog:max_bytes=_max_json_catalog_bytes(),error_type=StepCatalogError,label="step catalog",- ).decode("utf-8")+ ).decode("utf-8"),+ object_pairs_hook=_unique_json_fields,)+ except _DuplicateCatalogField:+ raiseexcept Exception as exc:if cache_safe and cache_file.exists():try:with open(cache_file, encoding="utf-8") as f:- cached = json.load(f)+ cached = json.load(f, object_pairs_hook=_unique_json_fields)if isinstance(cached, dict):return cached+ except _DuplicateCatalogField:+ raiseexcept (json.JSONDecodeError, ValueError, OSError):# Stale-cache read failed; let the original fetch error propagate.pass@@ -574,6 +594,8 @@ class StepCatalog:for entry in reversed(catalogs):try:data = self._fetch_single_catalog(entry, force_refresh)+ except _DuplicateCatalogField:+ raiseexcept StepCatalogError:fetch_errors += 1continue@@ -586,6 +608,7 @@ class StepCatalog:step_data["_install_allowed"] = entry.install_allowedmerged[step_id] = step_dataelif isinstance(steps, list):+ seen_in_source: set[str] = set()for step_data in steps:if not isinstance(step_data, dict):continue@@ -594,6 +617,11 @@ class StepCatalog:continuestep_id = str(raw_step_id).strip()if step_id:+ if step_id in seen_in_source:+ raise StepCatalogError(+ f"Duplicate step ID '{step_id}' in catalog '{entry.name}'."+ )+ seen_in_source.add(step_id)step_data["id"] = step_idstep_data["_catalog_name"] = entry.namestep_data["_install_allowed"] = entry.install_allowed@@ -609,10 +637,13 @@ class StepCatalog:query: str | None = None,) -> list[dict[str, Any]]:"""Search step types across all configured catalogs."""+ from ._versions import available_versions+merged = self._get_merged_steps()results: list[dict[str, Any]] = []for step_id, step_data in merged.items():+ available_versions(step_data, step_id)step_data.setdefault("id", step_id)if query:q = query.lower()@@ -628,13 +659,18 @@ class StepCatalog:results.append(step_data)return results- def get_step_info(self, step_id: str) -> dict[str, Any] | None:- """Get details for a specific step from the catalog."""+ def get_step_info(+ self, step_id: str, version: str | None = None+ ) -> dict[str, Any] | None:+ """Get the current or an exact release from the winning catalog."""+ from ._versions import select_release+merged = self._get_merged_steps()step = merged.get(step_id)if step:step.setdefault("id", step_id)- return step+ return select_release(step, step_id, version)+ return Nonedef get_catalog_configs(self) -> list[dict[str, Any]]:"""Return current catalog configuration as a list of dicts."""diff --git a/src/specify_cli/workflows/step/catalog/_versions.py b/src/specify_cli/workflows/step/catalog/_versions.pynew file mode 100644index 000000000..a54f715ef--- /dev/null+++ b/src/specify_cli/workflows/step/catalog/_versions.py@@ -0,0 +1,178 @@+"""Release selection for step catalog entries."""++from __future__ import annotations++import re+from pathlib import PurePosixPath+from typing import Any++from packaging.version import InvalidVersion, Version++from ._domain import StepCatalogError++_DIGEST = re.compile(r"[0-9a-fA-F]{64}\Z")+_CURRENT_ONLY = frozenset(+ {+ "version",+ "url",+ "step_yml_url",+ "init_url",+ "extra_files",+ "sha256",+ "requires",+ "provides",+ "releases",+ }+)+++def validate_checksums(entry: dict[str, Any], step_id: str, *, required: bool) -> None:+ """Check that a release pins exactly the files its installer downloads."""+ hashes = entry.get("sha256")+ if hashes is None and not required:+ return+ files = entry.get("extra_files", {})+ if not isinstance(files, dict) or any(+ not isinstance(path, str)+ or not path.strip()+ or "\\" in path+ or any(part in ("", ".", "..") for part in path.split("/"))+ or PurePosixPath(path).is_absolute()+ or path.casefold() in ("step.yml", "__init__.py")+ or not isinstance(url, str)+ or not url.strip()+ for path, url in files.items()+ ):+ raise StepCatalogError(f"Step '{step_id}' has invalid extra_files.")+ expected = {"step.yml", "__init__.py", *files}+ if (+ not isinstance(hashes, dict)+ or hashes.keys() != expected+ or any(+ not isinstance(value, str) or not _DIGEST.fullmatch(value)+ for value in hashes.values()+ )+ ):+ raise StepCatalogError(+ f"Step '{step_id}' needs SHA-256 digests for exactly {sorted(expected)}."+ )+++def _validated_releases(+ entry: dict[str, Any], step_id: str+) -> dict[str, dict[str, Any]]:+ if "releases" not in entry:+ return {}+ releases = entry["releases"]+ if not isinstance(releases, dict):+ raise StepCatalogError(f"Step '{step_id}' has an invalid releases mapping.")+ if entry.get("id", step_id) != step_id:+ raise StepCatalogError(f"Step '{step_id}' has a mismatched catalog ID.")+ current = entry.get("version")+ if not isinstance(current, str) or not current.strip():+ raise StepCatalogError(f"Step '{step_id}' has releases but no current version.")+ try:+ seen = {Version(current)}+ except InvalidVersion:+ raise StepCatalogError(+ f"Step '{step_id}' has invalid current version '{current}'."+ ) from None+ for release_version, record in releases.items():+ if not isinstance(release_version, str) or not release_version.strip():+ raise StepCatalogError(+ f"Step '{step_id}' has an invalid release version key."+ )+ try:+ normalized = Version(release_version)+ except InvalidVersion:+ raise StepCatalogError(+ f"Step '{step_id}' has invalid release version '{release_version}'."+ ) from None+ if normalized in seen:+ raise StepCatalogError(+ f"Step '{step_id}' repeats release version '{release_version}'."+ )+ seen.add(normalized)+ if not isinstance(record, dict):+ raise StepCatalogError(+ f"Step '{step_id}' release '{release_version}' must be an object."+ )+ if any(+ key in record+ for key in (+ "id",+ "version",+ "releases",+ "_catalog_name",+ "_install_allowed",+ )+ ):+ raise StepCatalogError(+ f"Step '{step_id}' release '{release_version}' "+ "contains reserved fields."+ )+ url = record.get("step_yml_url", record.get("url"))+ if (+ not isinstance(url, str)+ or not url.strip()+ or (+ "url" in record+ and "step_yml_url" in record+ and record["url"] != record["step_yml_url"]+ )+ ):+ raise StepCatalogError(+ f"Step '{step_id}' release '{release_version}' needs a step.yml URL."+ )+ init_url = record.get("init_url")+ if (+ init_url is not None+ and (not isinstance(init_url, str) or not init_url.strip())+ ) or (init_url is None and not url.endswith("step.yml")):+ raise StepCatalogError(+ f"Step '{step_id}' release '{release_version}' "+ "needs an __init__.py URL."+ )+ for field in ("requires", "provides"):+ if field in record and not isinstance(record[field], dict):+ raise StepCatalogError(+ f"Step '{step_id}' release '{release_version}' has invalid {field}."+ )+ validate_checksums(record, step_id, required=True)+ return releases+++def select_release(+ entry: dict[str, Any], step_id: str, version: str | None+) -> dict[str, Any] | None:+ """Select a release from the winning entry; never consult another source."""+ releases = _validated_releases(entry, step_id)+ 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:+ pass # Legacy versions still support exact spelling above.+ 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], step_id: str) -> list[str]:+ """List the advertised current version before historical versions."""+ releases = _validated_releases(entry, step_id)+ 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/workflows/step/command_add.py b/src/specify_cli/workflows/step/command_add.pyindex 363f88fed..4a0c2f55d 100644--- a/src/specify_cli/workflows/step/command_add.py+++ b/src/specify_cli/workflows/step/command_add.py@@ -8,6 +8,7 @@ directory, and ``--from`` archive URL). All three sources converge onfrom __future__ import annotations+import hashlibimport sysfrom typing import Annotated@@ -257,7 +258,9 @@ def _install_from_url(_print_installed(step_id, entry)-def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool) -> None:+def _install_from_catalog(+ project_root: cli.Path, step_id: str, *, force: bool, version: str | None = None+) -> None:"""Install a step package from the step catalog.The catalog fetch (URL/derivation/count preflight) stays a catalog concern;@@ -267,16 +270,23 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)from . import installerfrom .catalog import StepCatalog, StepCatalogError+ from .catalog._versions import validate_checksumscatalog = StepCatalog(project_root)try:- info = catalog.get_step_info(step_id)+ info = (+ catalog.get_step_info(step_id, version=version)+ if version is not None+ else catalog.get_step_info(step_id)+ )except StepCatalogError as exc:raise installer.StepInstallError(str(exc)) from excif not info:raise installer.StepInstallError(- f"Step type '{step_id}' not found in catalog"+ f"Step type '{step_id}' version '{version}' not found in the winning catalog"+ if version is not None+ else f"Step type '{step_id}' not found in catalog")if not info.get("_install_allowed", True):@@ -288,6 +298,12 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)cli.console.print("Direct installation is not enabled for this catalog source.")raise cli.typer.Exit(1)+ try:+ validate_checksums(info, step_id, required=version is not None)+ except StepCatalogError as exc:+ raise installer.StepInstallError(str(exc)) from exc+ checksums = info.get("sha256")+# Reject built-in collisions and duplicates before any download.installer.check_installable(project_root, step_id, force=force)@@ -379,6 +395,14 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)label="step package response",)+ def _fetch_checked(url: str, name: str) -> bytes:+ content = _safe_fetch(url)+ if checksums and (+ hashlib.sha256(content).hexdigest().lower() != checksums[name].lower()+ ):+ raise installer.StepInstallError(f"SHA-256 checksum mismatch for '{name}'")+ return content+try:package_tmp = tempfile.TemporaryDirectory(prefix="speckit-step-package-")except OSError as exc:@@ -389,8 +413,8 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)committed = Falsetry:try:- step_yml_content = _safe_fetch(step_yml_url)- init_py_content = _safe_fetch(init_url)+ step_yml_content = _fetch_checked(step_yml_url, "step.yml")+ init_py_content = _fetch_checked(init_url, "__init__.py")except Exception as exc:raise installer.StepInstallError(f"Failed to download step files: {exc}"@@ -442,7 +466,7 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)"directory") from Nonetry:- file_content = _safe_fetch(file_url)+ file_content = _fetch_checked(file_url, rel_path)except Exception as exc:raise installer.StepInstallError(f"Failed to download extra file '{rel_path}': {exc}"@@ -461,6 +485,24 @@ def _install_from_catalog(project_root: cli.Path, step_id: str, *, force: bool)f"Failed to write extra file '{rel_path}': {exc}") from exc+ if version is not None or "releases" in info:+ from packaging.version import InvalidVersion, Version++ step_meta = installer.validate_step_package(package_dir, step_id)+ declared_version = step_meta.get("version")+ try:+ matches = (+ isinstance(declared_version, str)+ and Version(declared_version) == Version(info["version"])+ )+ except (InvalidVersion, TypeError, KeyError):+ matches = False+ if not matches:+ raise installer.StepInstallError(+ f"step.yml version ({declared_version!r}) does not match "+ f"catalog version ({info.get('version')!r})"+ )+entry = installer.install_step_package(project_root,step_id,@@ -502,6 +544,10 @@ def workflow_step_add(dev: Annotated[str | None, cli.typer.Option("--dev", help="Install from a local step package directory")] = None,from_url: Annotated[str | None, cli.typer.Option("--from", help="Install from a .zip/.tar.gz/.tgz archive URL")] = None,force: Annotated[bool, cli.typer.Option("--force", help="Replace an existing installation")] = False,+ version: Annotated[+ str | None,+ cli.typer.Option("--version", help="Install an exact catalog release"),+ ] = None,):"""Install a custom step type from the catalog, a local directory, or a URL."""from . import installer@@ -519,6 +565,12 @@ def workflow_step_add(if from_url is not None and not from_url.strip():cli.console.print("[red]Error:[/red] --from value must not be empty")raise cli.typer.Exit(1)+ if version is not None and (dev is not None or from_url is not None):+ cli.console.print("[red]Error:[/red] --version requires a catalog step ID")+ raise cli.typer.Exit(1)+ if version is not None and not version.strip():+ cli.console.print("[red]Error:[/red] --version value must not be empty")+ raise cli.typer.Exit(1)step_helpers._validate_step_id_or_exit(step_id)@@ -528,7 +580,7 @@ def workflow_step_add(elif from_url is not None:_install_from_url(project_root, step_id, from_url, force=force)else:- _install_from_catalog(project_root, step_id, force=force)+ _install_from_catalog(project_root, step_id, force=force, version=version)except installer.StepInstallError as exc:notes = getattr(exc, "__notes__", ())for note in notes:diff --git a/src/specify_cli/workflows/step/command_info.py b/src/specify_cli/workflows/step/command_info.pyindex 6f70a0403..cc2b02399 100644--- a/src/specify_cli/workflows/step/command_info.py+++ b/src/specify_cli/workflows/step/command_info.py@@ -2,6 +2,8 @@from __future__ import annotations+from typing import Annotated+from .. import _commands as clifrom . import step_app@@ -26,6 +28,10 @@ def _format_source(installed_meta: dict) -> str:@step_app.command("info")def workflow_step_info(step_id: str = cli.typer.Argument(..., help="Step type ID"),+ versions: Annotated[+ bool,+ cli.typer.Option("--versions", help="List releases in the winning catalog"),+ ] = False,):"""Show details for a step type."""from .. import STEP_REGISTRY@@ -42,6 +48,12 @@ def workflow_step_info(is_builtin = builtin_step is not None and not installed_metaif is_builtin:+ if versions:+ cli.console.print(+ f"[red]Error:[/red] Built-in step type '{safe_step_id}' "+ "has no catalog releases"+ )+ raise cli.typer.Exit(1)cli.console.print(f"\n[bold cyan]{safe_step_id}[/bold cyan] [dim](built-in)[/dim]")@@ -49,6 +61,32 @@ def workflow_step_info(cli.console.print(" [green]Built-in step type[/green]")return+ if versions:+ from .catalog._versions import available_versions++ catalog = StepCatalog(project_root)+ try:+ info = catalog.get_step_info(step_id)+ if info is None:+ cli.console.print(+ f"[red]Error:[/red] Step type '{safe_step_id}' not found"+ )+ raise cli.typer.Exit(1)+ releases = available_versions(info, step_id)+ except StepCatalogError as exc:+ cli.console.print(f"[red]Error:[/red] {exc}")+ raise cli.typer.Exit(1)+ name = cli._escape_markup(str(info.get("name", step_id)))+ policy = (+ "" if info.get("_install_allowed", True)+ else " [dim](discovery only; not installable)[/dim]"+ )+ cli.console.print(f"\n[bold cyan]{name}[/bold cyan] ({safe_step_id}){policy}")+ for index, release in enumerate(releases):+ label = " (current)" if index == 0 else ""+ cli.console.print(f" {cli._escape_markup(release)}{label}")+ return+if installed_meta:name = cli._escape_markup(str(installed_meta.get("name", step_id)))version = cli._escape_markup(str(installed_meta.get("version", "?")))@@ -73,8 +111,9 @@ def workflow_step_info(catalog = StepCatalog(project_root)try:info = catalog.get_step_info(step_id)- except StepCatalogError:- info = None+ except StepCatalogError as exc:+ cli.console.print(f"[red]Error:[/red] {exc}")+ raise cli.typer.Exit(1)if info:name = cli._escape_markup(str(info.get("name", step_id)))diff --git a/tests/specify_cli/workflows/step/test_catalog_versions.py b/tests/specify_cli/workflows/step/test_catalog_versions.pynew file mode 100644index 000000000..dfdee40b4--- /dev/null+++ b/tests/specify_cli/workflows/step/test_catalog_versions.py@@ -0,0 +1,218 @@+"""Exact-release lookup for workflow step catalogs."""++from __future__ import annotations++import hashlib+import io++import pytest++from specify_cli.workflows.step.catalog import (+ StepCatalog,+ StepCatalogEntry,+ StepCatalogError,+)+from specify_cli.workflows.step.catalog._versions import available_versions+++def _digests(*extra: str) -> dict[str, str]:+ return {+ name: hashlib.sha256(name.encode()).hexdigest()+ for name in ("step.yml", "__init__.py", *extra)+ }+++def _entry() -> dict:+ return {+ "id": "deploy",+ "name": "Deploy",+ "version": "2.0",+ "url": "https://example.com/current/step.yml",+ "init_url": "https://example.com/current/__init__.py",+ "sha256": _digests(),+ "requires": {"current": True},+ "releases": {+ "1.0": {+ "step_yml_url": "https://example.com/old/step.yml",+ "init_url": "https://example.com/old/__init__.py",+ "extra_files": {"helper.py": "https://example.com/old/helper.py"},+ "sha256": _digests("helper.py"),+ "requires": {"old": True},+ },+ },+ }+++def test_current_and_exact_release_keep_separate_metadata(project_dir, monkeypatch):+ catalog = StepCatalog(project_dir)+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda: {"deploy": _entry()})++ current = catalog.get_step_info("deploy")+ old = catalog.get_step_info("deploy", version="v1.0")++ assert current["url"] == "https://example.com/current/step.yml"+ assert current["version"] == "2.0"+ assert current["releases"]["1.0"]["extra_files"]+ assert old["version"] == "1.0"+ assert old["step_yml_url"] == "https://example.com/old/step.yml"+ assert old["sha256"] == _digests("helper.py")+ assert old["requires"] == {"old": True}+ assert "url" not in old and "releases" not in old+ assert catalog.get_step_info("deploy", version="2.0")["url"] == current["url"]+ assert catalog.get_step_info("deploy", version="9.0") is None+ assert available_versions(current, "deploy") == ["2.0", "1.0"]+++def test_legacy_current_and_exact_spelling(project_dir, monkeypatch):+ catalog = StepCatalog(project_dir)+ legacy = {+ "id": "deploy",+ "version": "release-1",+ "url": "https://example.com/step.yml",+ }+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda: {"deploy": legacy})+ assert catalog.get_step_info("deploy") is legacy+ assert catalog.get_step_info("deploy", version="release-1") is legacy+ assert catalog.get_step_info("deploy", version="release-2") is None+++def test_winning_source_never_falls_back_for_missing_release(project_dir, monkeypatch):+ catalog = StepCatalog(project_dir)+ sources = [+ StepCatalogEntry("https://example.com/high", "discovery", 1, False),+ StepCatalogEntry("https://example.com/low", "installable", 2, True),+ ]+ high = {key: value for key, value in _entry().items() if key != "releases"}+ low = _entry()+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: sources)+ monkeypatch.setattr(+ catalog,+ "_fetch_single_catalog",+ lambda source, force_refresh=False: {+ "steps": {"deploy": high if source.name == "discovery" else low}+ },+ )+ assert catalog.get_step_info("deploy")["_install_allowed"] is False+ assert catalog.get_step_info("deploy", version="1.0") is None+++def test_list_catalog_rejects_duplicate_step_ids(project_dir, monkeypatch):+ catalog = StepCatalog(project_dir)+ source = StepCatalogEntry("https://example.com/steps.json", "test", 1, True)+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: [source])+ monkeypatch.setattr(+ catalog,+ "_fetch_single_catalog",+ lambda *_args, **_kwargs: {+ "steps": [+ {"id": "deploy", "version": "1.0"},+ {"id": "deploy", "version": "2.0"},+ ]+ },+ )+ with pytest.raises(StepCatalogError, match="Duplicate step ID 'deploy'"):+ catalog.get_step_info("deploy")++[email protected]("cached", [True, False])+def test_duplicate_json_release_key_is_not_silently_overwritten(+ project_dir, monkeypatch, cached+):+ from specify_cli.authentication import http as auth_http++ catalog = StepCatalog(project_dir)+ source = StepCatalogEntry("https://example.com/steps.json", "test", 1, True)+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: [source])+ payload = b'{"steps":{"deploy":{"version":"2.0","releases":{"1.0":{},"1.0":{}}}}}'+ if cached:+ cache_file, _ = catalog._get_cache_paths(source.url)+ cache_file.parent.mkdir(parents=True, exist_ok=True)+ cache_file.write_bytes(payload)+ monkeypatch.setattr(catalog, "_is_url_cache_valid", lambda _url: True)+ else:++ class Response(io.BytesIO):+ def geturl(self):+ return source.url++ def getheader(self, _name):+ return None++ monkeypatch.setattr(+ auth_http, "open_url", lambda *_args, **_kwargs: Response(payload)+ )+ with pytest.raises(StepCatalogError, match="Duplicate field '1.0'"):+ catalog.get_step_info("deploy", version="1.0")+++ ("change", "error"),+ [+ ({"releases": []}, "releases mapping"),+ ({"version": None}, "current version"),+ ({"version": "not valid"}, "current version"),+ ({"id": "another"}, "mismatched catalog ID"),+ ({"releases": {"v2.0": _entry()["releases"]["1.0"]}}, "repeats release"),+ (+ {+ "releases": {+ "1.0": _entry()["releases"]["1.0"],+ "v1.0": _entry()["releases"]["1.0"],+ }+ },+ "repeats release",+ ),+ ({"releases": {"bogus": {}}}, "invalid release version"),+ ({"releases": {"1.0": []}}, "must be an object"),+ ({"releases": {"1.0": {"id": "deploy"}}}, "reserved fields"),+ ({"releases": {"1.0": {"url": "https://example.com/step.yml"}}}, "SHA-256"),+ (+ {+ "releases": {+ "1.0": {+ **_entry()["releases"]["1.0"],+ "extra_files": {"./step.yml": "https://example.com/alias"},+ }+ }+ },+ "invalid extra_files",+ ),+ (+ {+ "releases": {+ "1.0": {+ **_entry()["releases"]["1.0"],+ "sha256": {"step.yml": "bad"},+ }+ }+ },+ "SHA-256",+ ),+ (+ {"releases": {"1.0": {**_entry()["releases"]["1.0"], "requires": []}}},+ "invalid requires",+ ),+ (+ {"releases": {"1.0": {**_entry()["releases"]["1.0"], "step_yml_url": 12}}},+ "step.yml URL",+ ),+ (+ {+ "releases": {+ "1.0": {+ **_entry()["releases"]["1.0"],+ "init_url": None,+ "step_yml_url": "https://example.com/old/manifest",+ }+ }+ },+ "__init__.py URL",+ ),+ ],+)+def test_bad_history_rejected_not_ignored(project_dir, monkeypatch, change, error):+ catalog = StepCatalog(project_dir)+ entry = {**_entry(), **change}+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda: {"deploy": entry})+ with pytest.raises(StepCatalogError, match=error):+ catalog.get_step_info("deploy")diff --git a/tests/specify_cli/workflows/step/test_command_add.py b/tests/specify_cli/workflows/step/test_command_add.pyindex f996628ce..191398b3f 100644--- a/tests/specify_cli/workflows/step/test_command_add.py+++ b/tests/specify_cli/workflows/step/test_command_add.py@@ -2,6 +2,7 @@from __future__ import annotations+import hashlibimport osimport pytest@@ -129,6 +130,7 @@ class TestWorkflowStepAddCLI:self, project_dir, monkeypatch):import tempfile+from typer.testing import CliRunnerfrom specify_cli import app@@ -290,12 +292,13 @@ class TestWorkflowStepAddCLI:self, project_dir, monkeypatch):import tempfile+from typer.testing import CliRunnerfrom specify_cli import appfrom specify_cli.authentication import http as auth_http- from specify_cli.workflows.step.catalog import StepCatalogfrom specify_cli.workflows.step import installer+ from specify_cli.workflows.step.catalog import StepCatalogmonkeypatch.chdir(project_dir)monkeypatch.setattr(@@ -1654,3 +1657,211 @@ class DevStep(StepBase):removed = runner.invoke(app, ["workflow", "step", "remove", "dev-step"])assert removed.exit_code == 0+class TestVersionedStepAdd:+ @staticmethod+ def _setup(project_dir, monkeypatch, *, discovery=False, corrupt=None):+ from specify_cli.authentication import http as auth_http+ from specify_cli.workflows.step.catalog import StepCatalog++ monkeypatch.chdir(project_dir)+ base = "https://example.com/old/"+ bodies = {+ base + "step.yml": b"step:\n type_key: deploy\n version: '1.0'\n",+ base + "__init__.py": b"# example\n",+ base + "helper.py": b"# helper\n",+ }+ hashes = {+ name: hashlib.sha256(bodies[base + name]).hexdigest()+ for name in ("step.yml", "__init__.py", "helper.py")+ }+ entry = {+ "id": "deploy",+ "name": "Deploy",+ "version": "2.0",+ "step_yml_url": "https://example.com/current/step.yml",+ "_install_allowed": not discovery,+ "releases": {+ "1.0": {+ "step_yml_url": base + "step.yml",+ "init_url": base + "__init__.py",+ "extra_files": {"helper.py": base + "helper.py"},+ "sha256": hashes,+ }+ },+ }+ if corrupt == "checksum":+ bodies[base + "helper.py"] = b"changed"+ elif corrupt == "version":+ bodies[base + "step.yml"] = b"step:\n type_key: deploy\n version: '2.0'\n"+ hashes["step.yml"] = hashlib.sha256(bodies[base + "step.yml"]).hexdigest()+ elif corrupt == "id":+ bodies[base + "step.yml"] = b"step:\n type_key: other\n version: '1.0'\n"+ hashes["step.yml"] = hashlib.sha256(bodies[base + "step.yml"]).hexdigest()+ elif corrupt == "url":+ entry["releases"]["1.0"]["init_url"] = "http://evil.example/__init__.py"+ monkeypatch.setattr(+ StepCatalog, "_get_merged_steps", lambda self: {"deploy": entry}+ )+ requested = []++ class Response:+ def __init__(self, url):+ self.url = url+ self.content = bodies[url]+ self.offset = 0++ def __enter__(self):+ return self++ def __exit__(self, *_args):+ return False++ def geturl(self):+ return self.url++ def getheader(self, _name):+ return None++ def read(self, size=-1):+ if size < 0:+ size = len(self.content)+ chunk = self.content[self.offset:self.offset + size]+ self.offset += len(chunk)+ return chunk++ def open_url(url, **_kwargs):+ requested.append(url)+ return Response(url)++ monkeypatch.setattr(auth_http, "open_url", open_url)+ return requested++ def test_install_exact_selected_files(self, project_dir, monkeypatch):+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.workflows.step.catalog import StepRegistry++ requested = self._setup(project_dir, monkeypatch)+ result = CliRunner().invoke(+ app, ["workflow", "step", "add", "deploy", "--version", "v1.0"]+ )+ assert result.exit_code == 0, result.output+ assert requested == [+ f"https://example.com/old/{name}"+ for name in ("step.yml", "__init__.py", "helper.py")+ ]+ assert StepRegistry(project_dir).get("deploy")["version"] == "1.0"+ assert (+ project_dir / ".specify/workflows/steps/deploy/helper.py"+ ).read_bytes() == b"# helper\n"++ @pytest.mark.parametrize(+ ("corrupt", "error"),+ [+ ("checksum", "checksum mismatch"),+ ("version", "does not match catalog version"),+ ("id", "does not match step ID"),+ ("url", "non-HTTPS"),+ ],+ )+ def test_rejects_bad_selected_release(+ self, project_dir, monkeypatch, corrupt, error+ ):+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.workflows.step.catalog import StepRegistry++ self._setup(project_dir, monkeypatch, corrupt=corrupt)+ result = CliRunner().invoke(+ app, ["workflow", "step", "add", "deploy", "--version", "1.0"]+ )+ assert result.exit_code == 1, result.output+ assert error in result.output+ assert not StepRegistry(project_dir).is_installed("deploy")+ assert not (project_dir / ".specify/workflows/steps/deploy").exists()++ @pytest.mark.parametrize(+ ("discovery", "version", "error"),+ [+ (False, "0.9", "not found in the winning catalog"),+ (True, "1.0", "discovery-only catalog"),+ ],+ )+ def test_no_fallback_or_discovery_install(+ self, project_dir, monkeypatch, discovery, version, error+ ):+ from typer.testing import CliRunner++ from specify_cli import app++ requested = self._setup(project_dir, monkeypatch, discovery=discovery)+ result = CliRunner().invoke(+ app, ["workflow", "step", "add", "deploy", "--version", version]+ )+ assert result.exit_code == 1, result.output+ assert error in result.output+ assert requested == []++ def test_current_explicit_selection_requires_digests(+ self, project_dir, monkeypatch+ ):+ from typer.testing import CliRunner++ from specify_cli import app++ requested = self._setup(project_dir, monkeypatch)+ result = CliRunner().invoke(+ app, ["workflow", "step", "add", "deploy", "--version", "2.0"]+ )+ assert result.exit_code == 1, result.output+ assert "SHA-256 digests" in result.output+ assert requested == []++ def test_rejects_insecure_redirect_before_following_it(+ self, project_dir, monkeypatch+ ):+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.authentication import http as auth_http++ self._setup(project_dir, monkeypatch)++ def redirect(url, *, redirect_validator, **_kwargs):+ redirect_validator(url, "http://evil.example/step.yml")+ raise AssertionError("redirect should have been refused")++ monkeypatch.setattr(auth_http, "open_url", redirect)+ result = CliRunner().invoke(+ app, ["workflow", "step", "add", "deploy", "--version", "1.0"]+ )+ assert result.exit_code == 1, result.output+ assert "redirect target must use HTTPS" in " ".join(result.output.split())+ assert not (project_dir / ".specify/workflows/steps/deploy").exists()++ @pytest.mark.parametrize("source_option", ["--dev", "--from"])+ def test_version_rejected_with_direct_source_before_network(+ self, project_dir, monkeypatch, source_option+ ):+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.authentication import http as auth_http++ monkeypatch.chdir(project_dir)+ monkeypatch.setattr(+ auth_http, "open_url",+ lambda *args, **kwargs: pytest.fail("direct source must not download"),+ )+ result = CliRunner().invoke(+ app,+ [+ "workflow", "step", "add", "deploy",+ source_option, "https://example.com/deploy.zip",+ "--version", "1.0",+ ],+ )+ assert result.exit_code == 1, result.output+ assert "--version requires a catalog step ID" in result.outputdiff --git a/tests/specify_cli/workflows/step/test_command_info.py b/tests/specify_cli/workflows/step/test_command_info.pyindex 62391f5f0..edee4d288 100644--- a/tests/specify_cli/workflows/step/test_command_info.py+++ b/tests/specify_cli/workflows/step/test_command_info.py@@ -106,3 +106,39 @@ class TestWorkflowStepRichMarkup:assert result.exit_code == 0, result.outputassert "catalog (default)" in result.output+++def test_info_versions_shows_current_and_history_from_discovery_catalog(+ project_dir, monkeypatch+):+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.workflows.step.catalog import StepCatalog++ monkeypatch.chdir(project_dir)+ monkeypatch.setattr(+ StepCatalog, "_get_merged_steps",+ lambda self: {+ "deploy": {+ "id": "deploy", "name": "Deploy", "version": "2.0",+ "_install_allowed": False,+ "releases": {+ "1.0": {+ "url": "https://example.com/1.0/step.yml",+ "sha256": {+ "step.yml": "0" * 64,+ "__init__.py": "1" * 64,+ },+ },+ },+ }+ },+ )+ result = CliRunner().invoke(+ app, ["workflow", "step", "info", "deploy", "--versions"]+ )+ assert result.exit_code == 0, result.output+ assert "2.0 (current)" in result.output+ assert "1.0" in result.output+ assert "discovery only; not installable" in result.output