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