💫 Toolkit to help you get started with SDD or any other process!
"""Resolve bundle component references against real, available components.
Used by ``specify bundle validate`` (FR-005 / SC-007) to confirm that every
declared component points at something installable. Resolution is offline-first:
a reference resolves when the component is bundled with Spec Kit or already
installed in the project; catalog sources are consulted only when network access
is permitted. Offline runs that cannot confirm a reference downgrade to a
warning rather than a false failure, while definitively-unknown references
always error.
"""
from __future__ import annotations
from pathlib import Path
from .manifest import ComponentRef
from .versioning import same_version
def _matches_pin(component: ComponentRef, actual: str | None) -> bool:
return component.version is None or (
bool(actual) and same_version(actual, component.version)
)
def _resolved_locally(root: Path, component: ComponentRef) -> bool:
kind = component.kind
try:
if component.source:
return False
from .primitives import _bundled_manifest_version, primitive_manager
if kind == "presets":
from .._assets import _locate_bundled_preset
bundled = _locate_bundled_preset(component.id)
if bundled is not None and _matches_pin(
component, _bundled_manifest_version(bundled / "preset.yml", "preset")
):
return True
if kind == "extensions":
from .._assets import _locate_bundled_extension
bundled = _locate_bundled_extension(component.id)
if bundled is not None and _matches_pin(
component, _bundled_manifest_version(bundled / "extension.yml", "extension")
):
return True
if kind == "workflows":
from .._assets import _locate_bundled_workflow
bundled = _locate_bundled_workflow(component.id)
if bundled is not None and _matches_pin(
component, _bundled_manifest_version(bundled / "workflow.yml", "workflow")
):
return True
if kind == "steps":
from ..workflows import BUILTIN_STEP_TYPES
# Step types ship with Spec Kit as built-ins (shell, gate, if, ...)
# rather than as an on-disk asset directory, so there is no
# ``_locate_bundled_step`` to mirror the three lookups above.
# ``BUILTIN_STEP_TYPES`` is the bundled-with-Spec-Kit check for this
# kind. Deliberately NOT ``STEP_REGISTRY``: ``load_custom_steps``
# adds project-installed ids to that process-global mapping and
# never removes them, so in a long-lived process a community step
# loaded for one project would be accepted as "bundled" when
# validating another. Without any bundled check at all, every
# built-in step type looked unresolved.
if component.id in BUILTIN_STEP_TYPES and component.version is None:
return True
manager = primitive_manager(kind, root, allow_network=False)
return manager.is_installed(component) and _matches_pin(
component, manager.installed_version(component)
)
except Exception: # noqa: BLE001 - resolution is best-effort
return False
return False
def _validate_pinned_install_metadata(component: ComponentRef, selected: dict) -> None:
from .._download_security import is_https_or_localhost_http
from . import BundlerError
def require_url(value: object, label: str) -> str:
if not isinstance(value, str) or not is_https_or_localhost_http(value):
raise BundlerError(
f"{component.kind[:-1]} '{component.id}' has an invalid {label} "
f"for pinned version {component.version}."
)
return value
if component.kind in ("extensions", "presets"):
from ..shared_infra import _SHA256_HEX_RE
require_url(selected.get("download_url"), "download URL")
digest = selected.get("sha256")
if digest is not None:
value = str(digest).strip()
if value[:7].lower() == "sha256:":
value = value[7:].strip()
if not _SHA256_HEX_RE.fullmatch(value.lower()):
raise BundlerError(
f"{component.kind[:-1]} '{component.id}' has an invalid SHA-256 "
f"digest for pinned version {component.version}."
)
return
if component.kind == "workflows":
from ..workflows.catalog._versions import _SHA256
require_url(selected.get("url"), "install URL")
digest = selected.get("sha256")
if digest is not None and (
not isinstance(digest, str) or not _SHA256.fullmatch(digest)
):
raise BundlerError(
f"workflow '{component.id}' has an invalid SHA-256 digest "
f"for pinned version {component.version}."
)
if "requires" in selected and not isinstance(selected["requires"], dict):
raise BundlerError(
f"workflow '{component.id}' has invalid requirements "
f"for pinned version {component.version}."
)
return
from ..workflows.step.catalog._versions import validate_checksums
validate_checksums(selected, component.id, required=True)
step_url = require_url(
selected.get("step_yml_url") or selected.get("url"), "step.yml URL"
)
init_url = selected.get("init_url")
if init_url is None:
if not step_url.endswith("step.yml"):
raise BundlerError(
f"step '{component.id}' has no __init__.py URL "
f"for pinned version {component.version}."
)
else:
require_url(init_url, "__init__.py URL")
for url in selected.get("extra_files", {}).values():
require_url(url, "extra file URL")
def _catalog_has_release(component: ComponentRef, catalog) -> bool:
from .component_catalog import select_catalog_release, winning_catalog_entry
current = winning_catalog_entry(catalog, component)
if current is None or not current.get("_install_allowed", True):
return False
if component.source and current.get("_catalog_name") != component.source:
return False
if component.version is None:
return True
if component.kind in ("extensions", "presets") and not current.get("version"):
# These legacy catalogs cannot attest a version; the primitive
# installer likewise accepts their unversioned current entry.
return True
selected = select_catalog_release(component, current)
if (
selected is None
or selected.get("_catalog_name") != current.get("_catalog_name")
or not selected.get("_install_allowed", True)
or not _matches_pin(component, selected.get("version"))
):
return False
if component.kind in ("extensions", "presets", "workflows", "steps"):
_validate_pinned_install_metadata(component, selected)
return True
def _resolved_in_catalog(root: Path, component: ComponentRef) -> bool | str | None:
"""Return the lookup result, a validation error, or None if unreachable."""
from ..extensions import ExtensionError
from ..presets import PresetError
from ..workflows.catalog import StepCatalogError, WorkflowCatalogError
from . import BundlerError
from .component_catalog import CatalogUnavailable
kind = component.kind
try:
if kind == "presets":
from ..presets import PresetCatalog
catalog = PresetCatalog(root)
return _catalog_has_release(component, catalog)
if kind == "extensions":
from ..extensions import ExtensionCatalog
catalog = ExtensionCatalog(root)
return _catalog_has_release(component, catalog)
if kind == "workflows":
from ..workflows.catalog import WorkflowCatalog
catalog = WorkflowCatalog(root)
return _catalog_has_release(component, catalog)
if kind == "steps":
from ..workflows.catalog import StepCatalog
catalog = StepCatalog(root)
return _catalog_has_release(component, catalog)
except (ConnectionError, TimeoutError):
return None
except CatalogUnavailable:
return None
except (BundlerError, ExtensionError, PresetError, WorkflowCatalogError, StepCatalogError) as exc:
return f"Catalog lookup failed: {exc}"
return None
def make_reference_checker(
project_root: Path,
*,
allow_network: bool,
warnings: list[str],
):
"""Build a ``ReferenceChecker`` for :func:`validate_manifest`.
Returns an error string for a reference that is definitively unresolvable,
``None`` otherwise. Unverifiable references (offline, or an unreachable
catalog) append a note to *warnings* and pass.
"""
def check(component: ComponentRef) -> str | None:
if _resolved_locally(project_root, component):
return None
if component.kind in ("presets", "extensions", "workflows") and component.source is None:
from . import BundlerError
from .primitives import _bundled_component_version, _bundled_pin_warning
from .versioning import is_newer_patch
kind = component.kind[:-1]
actual = _bundled_component_version(component)
if actual is not None and (
component.kind != "workflows"
or (component.version and is_newer_patch(actual, component.version))
):
try:
warning = _bundled_pin_warning(kind.capitalize(), component, actual)
except BundlerError as exc:
return str(exc)
if warning:
warnings.append(warning.message)
return None
if allow_network:
in_catalog = _resolved_in_catalog(project_root, component)
if in_catalog is True:
return None
if in_catalog is False:
return (
f"{component.kind[:-1]} '{component.id}' at "
f"{component.version or 'current'} is not available "
"locally or from the selected install-allowed catalog."
)
if isinstance(in_catalog, str):
return in_catalog
warnings.append(
f"Could not verify {component.kind[:-1]} '{component.id}' "
"(catalog unreachable); reference left unchecked."
)
return None
warnings.append(
f"Could not verify {component.kind[:-1]} '{component.id}' offline "
"(not bundled or installed); re-run validate online to check catalogs."
)
return None
return check