π« Toolkit to help you get started with SDD or any other process!
"""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