Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

14.4 KB
Raw Blame
"""Catalog models: source stack (priority + install policy) and catalog entries.

Mirrors ``contracts/bundle-catalog.schema.md``. The stack precedence is
project > user > built-in; install is permitted only from ``install-allowed``
sources.
"""
from __future__ import annotations

from dataclasses import dataclass, field, replace
from enum import Enum
from pathlib import Path
from typing import Any
from urllib.parse import urlparse
from . import BundlerError
from .manifest import _text
from .yamlio import ensure_within, load_yaml

CONFIG_FILENAME = "bundle-catalogs.yml"
# Supported bundle-catalogs.yml schema (major version). Both readers of the
# file β€” this module's _merge_config and commands_impl/catalog_config._read β€”
# reject an unsupported major version so a file written by a newer/incompatible
# Spec Kit fails fast instead of being parsed under the wrong assumptions.
CONFIG_SCHEMA_VERSION = "1.0"
CATALOG_SCHEMA_VERSION = "1.0"


class InstallPolicy(str, Enum):
    INSTALL_ALLOWED = "install-allowed"
    DISCOVERY_ONLY = "discovery-only"

    @classmethod
    def parse(cls, value: Any) -> "InstallPolicy":
        text = str(value or "").strip()
        for policy in cls:
            if policy.value == text:
                return policy
        raise BundlerError(
            f"Invalid install_policy '{value}' "
            f"(must be one of {[p.value for p in cls]})."
        )


class Scope(str, Enum):
    PROJECT = "project"
    USER = "user"
    BUILTIN = "built-in"


# Built-in default stack (used when no project/user config overrides it).
BUILTIN_DEFAULT_STACK: tuple[dict[str, Any], ...] = (
    {"id": "default", "url": "builtin://default", "priority": 1,
     "install_policy": InstallPolicy.INSTALL_ALLOWED.value},
    {"id": "community", "url": "builtin://community", "priority": 20,
     "install_policy": InstallPolicy.DISCOVERY_ONLY.value},
)


@dataclass(frozen=True)
class CatalogSource:
    id: str
    url: str
    priority: int
    install_policy: InstallPolicy
    scope: Scope = Scope.PROJECT

    @property
    def install_allowed(self) -> bool:
        return self.install_policy is InstallPolicy.INSTALL_ALLOWED

    @property
    def is_builtin(self) -> bool:
        """Whether this source is a ``builtin://`` catalog (packaged snapshot offline)."""
        try:
            return urlparse(self.url).scheme.lower() == "builtin"
        except ValueError:
            return False

    @classmethod
    def from_dict(cls, data: Any, scope: Scope) -> "CatalogSource":
        if not isinstance(data, dict):
            raise BundlerError("Each catalog source must be a mapping.")
        # ``_text`` rather than ``str(...get(k, ""))``: the default only covers a
        # *missing* key. A key present but null -- how YAML spells an empty field
        # (``id:`` with nothing after it) -- yields ``None``, and ``str(None)``
        # is the literal ``"None"``, which is truthy and so sailed straight past
        # the required-field guards below: a source with ``id: null`` was
        # accepted and registered under the name ``"None"``.
        source_id = _text(data.get("id"))
        url = _text(data.get("url"))
        if not source_id:
            raise BundlerError("A catalog source is missing its 'id'.")
        if not url:
            raise BundlerError(f"Catalog source '{source_id}' is missing its 'url'.")
        priority = data.get("priority")
        if priority is None:
            raise BundlerError(f"Catalog source '{source_id}' is missing its 'priority'.")
        if isinstance(priority, bool) or not isinstance(priority, (int, str)):
            raise BundlerError(
                f"Catalog source '{source_id}' has a non-integer priority: {priority!r}."
            )
        try:
            priority_int = int(priority)
        except (TypeError, ValueError):
            raise BundlerError(
                f"Catalog source '{source_id}' has a non-integer priority: {priority!r}."
            ) from None
        return cls(
            id=source_id,
            url=url,
            priority=priority_int,
            install_policy=InstallPolicy.parse(data.get("install_policy")),
            scope=scope,
        )

    def to_dict(self) -> dict[str, Any]:
        return {
            "id": self.id,
            "url": self.url,
            "priority": self.priority,
            "install_policy": self.install_policy.value,
        }


def _parse_tags(value: Any, entry_id: str) -> tuple[str, ...]:
    """Parse a catalog entry's ``tags`` into a tuple of strings.

    Catalogs are untrusted input: a bare string would otherwise be iterated
    character-by-character, so reject anything that is not a list/tuple, and
    reject any non-string member instead of silently coercing it.
    """
    if value is None:
        return ()
    if isinstance(value, (str, bytes)) or not isinstance(value, (list, tuple)):
        raise BundlerError(
            f"Catalog entry '{entry_id}': 'tags' must be a list of strings."
        )
    if any(not isinstance(item, str) for item in value):
        raise BundlerError(
            f"Catalog entry '{entry_id}': 'tags' must be a list of strings."
        )
    return tuple(value)


def _parse_verified(value: Any, entry_id: str) -> bool:
    """Validate a catalog entry's ``verified`` flag is a real boolean.

    ``bool("false")`` is truthy, so coercing arbitrary strings would silently
    mark untrusted entries as verified; require an actual boolean instead.
    """
    if isinstance(value, bool):
        return value
    raise BundlerError(
        f"Catalog entry '{entry_id}': 'verified' must be a boolean (true/false)."
    )


@dataclass(frozen=True)
class CatalogEntry:
    id: str
    name: str
    version: str
    role: str
    description: str
    author: str
    license: str
    download_url: str
    requires_speckit_version: str
    sha256: str | None = None
    provides: dict[str, int] = field(default_factory=dict)
    repository: str | None = None
    tags: tuple[str, ...] = ()
    verified: bool = False
    # Resolution provenance (filled in by the catalog stack at lookup time):
    source_id: str | None = None
    source_policy: InstallPolicy | None = None
    # Preserve unknown additive catalog fields for release-history materialization
    # without changing current-entry parsing.
    raw: dict[str, Any] | None = field(default=None, compare=False, repr=False)

    @classmethod
    def from_dict(cls, data: Any) -> "CatalogEntry":
        if not isinstance(data, dict):
            raise BundlerError("Each catalog entry must be a mapping.")
        # ``_text`` here too: an ``id: null`` otherwise became the literal
        # "None", which is truthy, so ``load_catalog_payload`` reported it as an
        # id MISMATCH against the mapping key rather than the accurate
        # missing-id error.
        entry_id = _text(data.get("id"))
        # `or {}` would coerce a FALSY non-mapping (0, '', False, []) to {} before
        # the isinstance guard, silently accepting a corrupt catalog entry; only
        # an absent/None value means "not present".
        requires = data.get("requires")
        if requires is None:
            requires = {}
        elif not isinstance(requires, dict):
            raise BundlerError(
                f"Catalog entry '{entry_id or '<unknown>'}': 'requires' must be a "
                "mapping when present."
            )
        provides_raw = data.get("provides")
        if provides_raw is None:
            provides_raw = {}
        elif not isinstance(provides_raw, dict):
            raise BundlerError(
                f"Catalog entry '{entry_id or '<unknown>'}': 'provides' must be a "
                "mapping when present."
            )
        return cls(
            id=entry_id,
            # See the note in ``CatalogSource.from_dict``: an explicitly null
            # field must read as empty, not as the literal string "None".
            name=_text(data.get("name")),
            version=_text(data.get("version")),
            role=_text(data.get("role")),
            description=_text(data.get("description")),
            author=_text(data.get("author")),
            license=_text(data.get("license")),
            download_url=_text(data.get("download_url")),
            requires_speckit_version=_text(requires.get("speckit_version")),
            sha256=(
                None
                if data.get("sha256") is None
                else str(data["sha256"]).strip()
            ),
            provides=dict(provides_raw),
            repository=(str(data["repository"]) if data.get("repository") else None),
            tags=_parse_tags(data.get("tags"), entry_id),
            verified=_parse_verified(data.get("verified", False), entry_id),
            raw=dict(data),
        )

    def with_provenance(self, source: CatalogSource) -> "CatalogEntry":
        return replace(
            self,
            source_id=source.id,
            source_policy=source.install_policy,
        )


def load_catalog_payload(data: Any) -> dict[str, CatalogEntry]:
    """Parse a catalog JSON payload into ``{bundle_id: CatalogEntry}``."""
    if not isinstance(data, dict):
        raise BundlerError("Catalog payload must be a JSON object.")
    schema_version = data.get("schema_version")
    if schema_version is not None and (
        str(schema_version).strip().split(".")[0]
        != CATALOG_SCHEMA_VERSION.split(".")[0]
    ):
        raise BundlerError(
            f"Unsupported catalog schema version "
            f"'{str(schema_version).strip()}'; this Spec Kit understands "
            f"version {CATALOG_SCHEMA_VERSION}."
        )
    bundles_raw = data.get("bundles")
    if not isinstance(bundles_raw, dict):
        raise BundlerError("Catalog payload is missing a 'bundles' object.")
    entries: dict[str, CatalogEntry] = {}
    # Function-local import avoids the catalogs -> catalog_versions import cycle.
    from .catalog_versions import _validated_releases

    for bundle_id, entry_raw in bundles_raw.items():
        key = str(bundle_id)
        entry = CatalogEntry.from_dict(entry_raw)
        # The enclosing key is the authoritative bundle id used by
        # search/resolve/install. Reject entries whose own ``id`` is missing or
        # disagrees with the key, so a malformed or malicious catalog can't list
        # an id that resolves to a different (or no) bundle.
        if not entry.id:
            raise BundlerError(
                f"Catalog entry for '{key}' is missing its 'id' field."
            )
        if entry.id != key:
            raise BundlerError(
                f"Catalog entry id mismatch: key '{key}' != entry id "
                f"'{entry.id}'."
            )
        _validated_releases(entry)
        entries[key] = entry
    return entries


def load_source_stack(project_root: Path, user_config_dir: Path | None = None) -> list[CatalogSource]:
    """Build the effective, priority-sorted source stack (project > user > built-in).

    A source id present at a higher-precedence scope overrides the same id at a
    lower scope. The built-in default stack is always the fallback.
    """
    by_id: dict[str, CatalogSource] = {}

    # Lowest precedence first; later writes override earlier ones for the same id.
    for raw in BUILTIN_DEFAULT_STACK:
        src = CatalogSource.from_dict(raw, Scope.BUILTIN)
        by_id[src.id] = src

    if user_config_dir is not None:
        _merge_config(by_id, Path(user_config_dir) / CONFIG_FILENAME, Scope.USER)

    # Confine the project-scoped read: refuse a symlinked .specify/ that
    # resolves outside the project root (consistent with other guarded reads).
    project_config = Path(project_root) / ".specify" / CONFIG_FILENAME
    if project_config.exists():
        ensure_within(project_root, project_config)
    _merge_config(by_id, project_config, Scope.PROJECT)

    return sorted(by_id.values(), key=lambda s: (s.priority, s.id))


def _merge_config(by_id: dict[str, CatalogSource], config_path: Path, scope: Scope) -> None:
    if not config_path.exists():
        return
    # ``load_yaml`` returns ``{}`` only for an empty document and the raw parse
    # otherwise, so a non-mapping top level (a YAML list or scalar, including
    # the falsy ``[]``/``false``/``0``/``''``) is caught here and raised β€”
    # matching the sibling reader commands_impl/catalog_config._read. #3623
    # aligned the inner non-list ``catalogs`` value between the two readers.
    data = load_yaml(config_path)
    if not isinstance(data, dict):
        raise BundlerError(
            f"Malformed catalog config at {config_path}: expected a mapping at "
            f"the top level, got {type(data).__name__}."
        )
    # Reject an unsupported major schema version, matching the sibling reader
    # commands_impl/catalog_config._read. Without this, a file written by a
    # newer/incompatible Spec Kit was silently parsed under v1 assumptions on
    # the resolution path (bundle search/install), while the other reader
    # rejected it β€” the two readers disagreed. An absent schema_version stays
    # valid (backward compatible with configs that omit it).
    schema_version = data.get("schema_version")
    if schema_version is not None and (
        str(schema_version).strip().split(".")[0]
        != CONFIG_SCHEMA_VERSION.split(".")[0]
    ):
        raise BundlerError(
            f"Unsupported catalog config schema version "
            f"'{str(schema_version).strip()}' at {config_path}; this Spec Kit "
            f"understands version {CONFIG_SCHEMA_VERSION}. The file may have been "
            "written by a newer version or is corrupt."
        )
    catalogs = data.get("catalogs")
    if catalogs is None:
        return
    if not isinstance(catalogs, list):
        # Treat only an absent/``None`` ``catalogs`` as "nothing to merge"; any
        # other non-list value (``catalogs: 5``, ``false``, ``0``, ``''``,
        # ``{}``) is a malformed config and must raise, not be silently skipped
        # by a falsy check. Otherwise a truthy scalar would raise a raw
        # ``TypeError: 'int' object is not iterable`` from the loop below, while
        # falsy non-lists would be swallowed. Report the same actionable
        # BundlerError the sibling reader of this file raises
        # (commands_impl/catalog_config.py) so both readers of
        # bundle-catalogs.yml agree. An empty list stays valid (loop is a no-op).
        raise BundlerError(
            f"Malformed catalog config at {config_path}: 'catalogs' must be a "
            f"list, got {type(catalogs).__name__}."
        )
    for raw in catalogs:
        src = CatalogSource.from_dict(raw, scope)
        by_id[src.id] = src