Class StepCatalog

src/specify_cli/workflows/catalog.py:737–1199

Manages step catalog fetching, caching, and searching. Resolution order for catalog sources: 1. ``SPECKIT_STEP_CATALOG_URL`` env var (overrides all) 2. Project-level ``.specify/step-catalogs.yml`` 3. User-level ``~/.specify/step-catalogs.yml`` 4. Built-in defaults (official + co

class StepCatalog:
    """Manages step catalog fetching, caching, and searching.

    Resolution order for catalog sources:
    1. ``SPECKIT_STEP_CATALOG_URL`` env var (overrides all)
    2. Project-level ``.specify/step-catalogs.yml``
    3. User-level ``~/.specify/step-catalogs.yml``
    4. Built-in defaults (official + community)
    """

    DEFAULT_CATALOG_URL = (
        "https://raw.githubusercontent.com/github/spec-kit/main/"
        "workflows/step-catalog.json"
    )
    COMMUNITY_CATALOG_URL = (
        "https://raw.githubusercontent.com/github/spec-kit/main/"
        "workflows/step-catalog.community.json"
    )
    CACHE_DURATION = 3600  # 1 hour

    def __init__(self, project_root: Path) -> None:
        self.project_root = project_root
        self.steps_dir = project_root / ".specify" / "workflows" / "steps"
        self.cache_dir = self.steps_dir / ".cache"

    def _is_cache_path_safe(self) -> bool:
        """Return False if any component of the cache path is a symlink."""
        current = self.project_root
        for part in (".specify", "workflows", "steps", ".cache"):
            current = current / part
            if current.is_symlink():
                return False
        return True

    # -- Catalog resolution -----------------------------------------------

    def _validate_catalog_url(self, url: str) -> None:
        """Validate that a catalog URL uses HTTPS (localhost HTTP allowed)."""
        from urllib.parse import urlparse

        parsed = urlparse(url)
        is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
        if parsed.scheme != "https" and not (
            parsed.scheme == "http" and is_localhost
        ):
            raise StepValidationError(
                f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
                "HTTP is only allowed for localhost."
            )
        if not parsed.hostname:
            raise StepValidationError(
                "Catalog URL must be a valid URL with a host."
            )

    def _load_catalog_config(
        self, config_path: Path
    ) -> list[StepCatalogEntry] | None:
        """Load catalog stack configuration from a YAML file."""