Skip to content

💫 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.md
index 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 and
then 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
```bash
diff --git a/src/specify_cli/workflows/step/catalog/_domain.py b/src/specify_cli/workflows/step/catalog/_domain.py
index 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:
+ raise
except (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:
+ raise
except 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:
+ raise
except (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:
+ raise
except StepCatalogError:
fetch_errors += 1
continue
@@ -586,6 +608,7 @@ class StepCatalog:
step_data["_install_allowed"] = entry.install_allowed
merged[step_id] = step_data
elif 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:
continue
step_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_id
step_data["_catalog_name"] = entry.name
step_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 None
def 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.py
new file mode 100644
index 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.py
index 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 on
from __future__ import annotations
+import hashlib
import sys
from 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 installer
from .catalog import StepCatalog, StepCatalogError
+ from .catalog._versions import validate_checksums
catalog = 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 exc
if 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 = False
try:
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 None
try:
- 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.py
index 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 cli
from . 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_meta
if 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.py
new file mode 100644
index 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.py
index 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 hashlib
import os
import pytest
@@ -129,6 +130,7 @@ class TestWorkflowStepAddCLI:
self, project_dir, monkeypatch
):
import tempfile
+
from typer.testing import CliRunner
from specify_cli import app
@@ -290,12 +292,13 @@ class TestWorkflowStepAddCLI:
self, project_dir, monkeypatch
):
import tempfile
+
from typer.testing import CliRunner
from specify_cli import app
from specify_cli.authentication import http as auth_http
- from specify_cli.workflows.step.catalog import StepCatalog
from specify_cli.workflows.step import installer
+ from specify_cli.workflows.step.catalog import StepCatalog
monkeypatch.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.output
diff --git a/tests/specify_cli/workflows/step/test_command_info.py b/tests/specify_cli/workflows/step/test_command_info.py
index 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.output
assert "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