Skip to content

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

15.1 KB
Raw Blame
"""Bundle manifest model (``bundle.yml``) β€” parsing and structural normalization.

Mirrors ``contracts/bundle-manifest.schema.md``. Structural validation (shape,
required fields, enum/semver checks) lives here; *reference* resolution against a
catalog stack lives in the validator/resolver services.
"""
from __future__ import annotations

import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

from . import BundlerError
from .versioning import is_semver
from .yamlio import load_yaml

SUPPORTED_SCHEMA_VERSIONS = {"1.0", "1.1"}
PRESET_STRATEGIES = {"replace", "prepend", "append", "wrap"}

COMPONENT_KINDS = ("extensions", "presets", "steps", "workflows")

# A bundle id must be a filesystem-safe slug: it is interpolated into artifact
# filenames (e.g. ``<id>-<version>.zip``), so path separators or traversal
# segments must never appear.
_SAFE_BUNDLE_ID = re.compile(r"^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$")


@dataclass(frozen=True)
class ComponentRef:
    """A pointer to an existing Spec Kit primitive a bundle installs."""

    kind: str  # one of COMPONENT_KINDS (singularized concept), stored plural-of-origin
    id: str
    version: str | None = None
    source: str | None = None
    priority: int | None = None  # extensions and presets only
    strategy: str | None = None  # presets only

    def label(self) -> str:
        return f"{self.kind[:-1]}:{self.id}@{self.version or 'unpinned'}"


@dataclass(frozen=True)
class BundleRef:
    """A pointer to another bundle, pinned to an exact version."""

    id: str
    version: str | None = None
    source: str | None = None  # expected winning bundle catalog ID

    def label(self) -> str:
        return f"bundle:{self.id}@{self.version or 'unpinned'}"


@dataclass(frozen=True)
class IntegrationRef:
    id: str


@dataclass(frozen=True)
class Requires:
    speckit_version: str
    tools: tuple[str, ...] = ()
    mcp: tuple[str, ...] = ()


@dataclass(frozen=True)
class BundleMeta:
    id: str
    name: str
    version: str
    role: str
    description: str
    author: str
    license: str


@dataclass
class BundleManifest:
    schema_version: str
    bundle: BundleMeta
    requires: Requires
    integration: IntegrationRef | None = None
    extensions: list[ComponentRef] = field(default_factory=list)
    presets: list[ComponentRef] = field(default_factory=list)
    steps: list[ComponentRef] = field(default_factory=list)
    workflows: list[ComponentRef] = field(default_factory=list)
    bundles: list[BundleRef] = field(default_factory=list)
    tags: tuple[str, ...] = ()
    source_path: Path | None = None

    @property
    def components(self) -> list[ComponentRef]:
        """Own installable component references in deterministic order.

        Excludes ``bundles``: referenced bundles are expanded separately.
        """
        return [*self.extensions, *self.presets, *self.steps, *self.workflows]

    # -- construction ---------------------------------------------------------

    @classmethod
    def from_file(cls, path: Path) -> BundleManifest:
        data = load_yaml(path)
        manifest = cls.from_dict(data)
        manifest.source_path = Path(path)
        return manifest

    @classmethod
    def from_dict(cls, data: Any) -> BundleManifest:
        if not isinstance(data, dict):
            raise BundlerError("Manifest must be a YAML mapping at the top level.")

        schema_version = _text(data.get("schema_version"))

        bundle_raw = data.get("bundle")
        if not isinstance(bundle_raw, dict):
            raise BundlerError("Manifest is missing the required 'bundle' mapping.")
        meta = BundleMeta(
            id=_text(bundle_raw.get("id")),
            name=_text(bundle_raw.get("name")),
            version=_text(bundle_raw.get("version")),
            role=_text(bundle_raw.get("role")),
            description=_text(bundle_raw.get("description")),
            author=_text(bundle_raw.get("author")),
            license=_text(bundle_raw.get("license")),
        )

        requires_raw = data.get("requires")
        if requires_raw is None:
            requires_raw = {}
        elif not isinstance(requires_raw, dict):
            raise BundlerError("'requires' must be a mapping when present.")
        requires = Requires(
            speckit_version=_text(requires_raw.get("speckit_version")),
            tools=_parse_str_list(requires_raw.get("tools"), "requires.tools"),
            mcp=_parse_str_list(requires_raw.get("mcp"), "requires.mcp"),
        )

        integration = None
        integration_raw = data.get("integration")
        # Mirror the requires/provides guards above: a present-but-non-mapping
        # 'integration' (e.g. a bare string "copilot") was silently dropped,
        # leaving the bundle wrongly integration-agnostic. Reject it instead.
        if integration_raw is not None and not isinstance(integration_raw, dict):
            raise BundlerError("'integration' must be a mapping when present.")
        if isinstance(integration_raw, dict):
            # A mapping without a usable id was silently mishandled: a
            # missing or empty id fell through to integration=None (the
            # declared integration was dropped and the bundle validated as
            # integration-agnostic), while a whitespace-only id passed the
            # old truthiness check and became IntegrationRef(id="").
            # Reject all three instead.
            integration_id = _text(integration_raw.get("id"))
            if not integration_id:
                raise BundlerError(
                    "'integration' mapping must include a non-empty 'id'."
                )
            integration = IntegrationRef(id=integration_id)

        provides = data.get("provides")
        if provides is None:
            provides = {}
        elif not isinstance(provides, dict):
            raise BundlerError("'provides' must be a mapping when present.")

        tags_raw = data.get("tags")
        if tags_raw is None:
            tags_raw = []
        else:
            tags_raw = _parse_str_list(tags_raw, "tags")

        manifest = cls(
            schema_version=schema_version,
            bundle=meta,
            requires=requires,
            integration=integration,
            extensions=_parse_refs("extensions", provides.get("extensions")),
            presets=_parse_refs("presets", provides.get("presets")),
            steps=_parse_refs("steps", provides.get("steps")),
            workflows=_parse_refs("workflows", provides.get("workflows")),
            bundles=_parse_bundle_refs(provides.get("bundles")),
            tags=tuple(str(t) for t in tags_raw),
        )
        return manifest

    # -- structural validation ------------------------------------------------

    def structural_errors(self) -> list[str]:
        """Return a list of human-readable structural problems (empty == valid)."""
        errors: list[str] = []

        if self.schema_version not in SUPPORTED_SCHEMA_VERSIONS:
            errors.append(
                f"schema_version '{self.schema_version or '<missing>'}' is not supported "
                f"(supported: {sorted(SUPPORTED_SCHEMA_VERSIONS)})."
            )

        required = {
            "bundle.id": self.bundle.id,
            "bundle.name": self.bundle.name,
            "bundle.version": self.bundle.version,
            "bundle.role": self.bundle.role,
            "bundle.description": self.bundle.description,
            "bundle.author": self.bundle.author,
            "bundle.license": self.bundle.license,
            "requires.speckit_version": self.requires.speckit_version,
        }
        for field_path, value in required.items():
            if not value:
                errors.append(f"Missing required field: {field_path}.")

        if self.bundle.version and not is_semver(self.bundle.version):
            errors.append(f"bundle.version '{self.bundle.version}' is not valid semver.")

        if self.bundle.id and not _SAFE_BUNDLE_ID.match(self.bundle.id):
            errors.append(
                f"bundle.id '{self.bundle.id}' must be a slug "
                "(lowercase letters, digits, '.', '_', '-'; no path separators)."
            )

        seen_components: set[tuple[str, str]] = set()
        for ref in self.components:
            if not ref.id:
                errors.append(f"A {ref.kind[:-1]} entry is missing its 'id'.")
            elif (ref.kind, ref.id) in seen_components:
                errors.append(
                    f"Duplicate {ref.kind[:-1]} '{ref.id}' in provides; "
                    "declare each component ID only once per kind."
                )
            else:
                seen_components.add((ref.kind, ref.id))
            if ref.kind != "steps" and not ref.version:
                errors.append(
                    f"{ref.kind[:-1]} '{ref.id or '<unknown>'}' must be pinned to a 'version'."
                )
            if ref.version and not is_semver(ref.version):
                errors.append(
                    f"{ref.kind[:-1]} '{ref.id}' has invalid version '{ref.version}'."
                )
            # Preset and extension installs refuse a priority below 1, which
            # would otherwise surface only mid-install, after earlier components.
            if (
                ref.kind in ("extensions", "presets")
                and ref.priority is not None
                and ref.priority < 1
            ):
                errors.append(
                    f"{ref.kind[:-1]} '{ref.id}' priority must be 1 or higher, "
                    f"got {ref.priority}."
                )

        if self.bundles and self.schema_version != "1.1":
            errors.append('Bundle references require schema_version "1.1".')

        seen_bundles: set[str] = set()
        for bundle_ref in self.bundles:
            if not bundle_ref.id:
                errors.append("A bundle reference is missing its 'id'.")
            else:
                if not _SAFE_BUNDLE_ID.match(bundle_ref.id):
                    errors.append(
                        f"Bundle reference id '{bundle_ref.id}' must be a slug "
                        "(lowercase letters, digits, '.', '_', '-'; no path separators)."
                    )
                if bundle_ref.id in seen_bundles:
                    errors.append(
                        f"Duplicate bundle reference '{bundle_ref.id}' in provides; "
                        "declare each bundle reference only once."
                    )
                seen_bundles.add(bundle_ref.id)
                if bundle_ref.id == self.bundle.id:
                    errors.append(
                        f"Bundle reference '{bundle_ref.id}' is invalid: "
                        "a bundle cannot reference itself."
                    )
            if not bundle_ref.version:
                errors.append(
                    f"bundle reference '{bundle_ref.id or '<unknown>'}' "
                    "must be pinned to a 'version'."
                )
            elif not is_semver(bundle_ref.version):
                errors.append(
                    f"bundle reference '{bundle_ref.id}' has invalid version "
                    f"'{bundle_ref.version}'."
                )

        for ref in self.presets:
            if ref.priority is None:
                errors.append(f"preset '{ref.id}' must declare an integer 'priority'.")
            if ref.strategy is None or ref.strategy not in PRESET_STRATEGIES:
                errors.append(
                    f"preset '{ref.id}' has invalid strategy '{ref.strategy}' "
                    f"(must be one of {sorted(PRESET_STRATEGIES)})."
                )

        return errors

    def is_agnostic(self) -> bool:
        """True when the bundle declares no integration (inherits the active one)."""
        return self.integration is None


def _text(raw: Any) -> str:
    """Coerce a manifest scalar into stripped text, mapping an explicit null to ``""``.

    A ``.get(key, "")`` default only covers a *missing* key. A key that is
    present but null -- how YAML spells an empty field (``author:`` with nothing
    after it) -- yields ``None``, and ``str(None)`` is the literal ``"None"``.
    That text is non-empty, so it sailed past the ``if not value`` required-field
    checks in :meth:`BundleManifest.structural_errors`: an empty required field
    was silently accepted and the bundle shipped ``"None"`` as its
    author/license/description.
    """
    if raw is None:
        return ""
    return str(raw).strip()


def _parse_str_list(raw: Any, field_name: str) -> tuple[str, ...]:
    """Parse a manifest list-of-strings field into a tuple of strings.

    Rejects a bare string/bytes (which would otherwise be iterated
    character-by-character), any non-list/tuple, and any non-string member,
    matching the manifest contract (``string[]``).
    """
    if raw is None:
        return ()
    if isinstance(raw, (str, bytes)) or not isinstance(raw, (list, tuple)):
        raise BundlerError(f"'{field_name}' must be a list of strings when present.")
    if any(not isinstance(item, str) for item in raw):
        raise BundlerError(f"'{field_name}' must be a list of strings when present.")
    return tuple(raw)


def _parse_refs(kind: str, raw: Any) -> list[ComponentRef]:
    if raw is None:
        return []
    if not isinstance(raw, list):
        raise BundlerError(f"provides.{kind} must be a list when present.")
    refs: list[ComponentRef] = []
    for item in raw:
        if not isinstance(item, dict):
            raise BundlerError(f"Each provides.{kind} entry must be a mapping.")
        priority = _parse_priority(kind, item.get("priority"))
        refs.append(
            ComponentRef(
                kind=kind,
                id=_text(item.get("id")),
                version=(str(item["version"]).strip() if item.get("version") else None),
                source=(str(item["source"]).strip() if item.get("source") else None),
                priority=priority,
                strategy=(str(item["strategy"]).strip() if item.get("strategy") else None),
            )
        )
    return refs


def _parse_bundle_refs(raw: Any) -> list[BundleRef]:
    if raw is None:
        return []
    if not isinstance(raw, list):
        raise BundlerError("provides.bundles must be a list when present.")
    refs: list[BundleRef] = []
    for item in raw:
        if not isinstance(item, dict):
            raise BundlerError("Each provides.bundles entry must be a mapping.")
        refs.append(
            BundleRef(
                id=_text(item.get("id")),
                version=_optional_text(item.get("version")),
                source=_optional_text(item.get("source")),
            )
        )
    return refs


def _optional_text(raw: Any) -> str | None:
    """Stripped text, with unset, empty and whitespace-only values as ``None``."""
    if not raw:
        return None
    return str(raw).strip() or None


def _parse_priority(kind: str, raw: Any) -> int | None:
    if raw is None:
        return None
    if isinstance(raw, bool) or not isinstance(raw, (int, str)):
        raise BundlerError(
            f"provides.{kind} priority must be an integer, got {raw!r}."
        )
    try:
        return int(raw)
    except (TypeError, ValueError):
        raise BundlerError(
            f"provides.{kind} priority must be an integer, got {raw!r}."
        ) from None