π« Toolkit to help you get started with SDD or any other process!
"""Installed-bundle records β requirements and ownership for list/remove/update.
Records are stored as JSON at ``.specify/bundle-records.json``. Each record
stores every required component for conflict detection and separately records
which components the bundle contributed, so removal never touches independently
installed components (FR-022, SC-004). Known installed
versions are stored separately from requested pins to make patch substitutions
visible without changing bundle ownership or manifest identity.
"""
from __future__ import annotations
from dataclasses import dataclass, field, replace
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from . import BundlerError
from .yamlio import dump_json, ensure_within, load_json
from .manifest import COMPONENT_KINDS, BundleRef, ComponentRef, _text
RECORDS_FILENAME = "bundle-records.json"
RECORDS_SCHEMA_VERSION = "1.0"
@dataclass(frozen=True)
class InstalledBundleRecord:
bundle_id: str
version: str
contributed_components: tuple[ComponentRef, ...]
required_components: tuple[ComponentRef, ...]
installed_at: str
installed_versions: dict[str, str] = field(default_factory=dict)
bundle_references: tuple[BundleRef, ...] = ()
@classmethod
def create(
cls,
bundle_id: str,
version: str,
components: list[ComponentRef],
installed_at: str | None = None,
required_components: list[ComponentRef] | None = None,
installed_versions: dict[str, str] | None = None,
bundle_references: list[BundleRef] | None = None,
) -> "InstalledBundleRecord":
return cls(
bundle_id=bundle_id,
version=version,
contributed_components=tuple(components),
required_components=tuple(
components if required_components is None else required_components
),
installed_at=installed_at or _utc_now(),
installed_versions=(
dict(installed_versions) if installed_versions is not None else {}
),
bundle_references=(
tuple(bundle_references) if bundle_references is not None else ()
),
)
def to_dict(self) -> dict[str, Any]:
data: dict[str, Any] = {
"bundle_id": self.bundle_id,
"version": self.version,
"installed_at": self.installed_at,
"contributed_components": [
_component_to_dict(c) for c in self.contributed_components
],
"required_components": [
_component_to_dict(c) for c in self.required_components
],
}
if self.installed_versions:
data["installed_versions"] = dict(self.installed_versions)
if self.bundle_references:
data["bundle_references"] = [
_bundle_reference_to_dict(reference)
for reference in self.bundle_references
]
return data
@classmethod
def from_dict(cls, data: Any) -> "InstalledBundleRecord":
if not isinstance(data, dict):
raise BundlerError("Each installed-bundle record must be a mapping.")
components_raw = data.get("contributed_components")
if components_raw is None:
components_raw = []
elif not isinstance(components_raw, list):
# `or []` would coerce a FALSY non-list (0, '', False, {}) to []
# before this guard, silently accepting a corrupt record; only an
# absent/None value means "no components".
raise BundlerError(
"Corrupt record: 'contributed_components' must be a list."
)
# Older records contain only contributed components. Retain those
# known pins until a successful reinstall writes the full requirements.
required_raw = data.get("required_components", components_raw)
if not isinstance(required_raw, list):
raise BundlerError(
"Corrupt record: 'required_components' must be a list."
)
# ``.get(key, "")`` defaults only a *missing* key. A key that is
# present but null -- how a hand-edited or corrupt record spells an
# empty field -- yields ``None``, and ``str(None)`` is the non-empty
# literal ``"None"``, which sails past the required-field checks
# below. Reuse the manifest's ``_text`` so records and bundle.yml
# agree on what an explicit null means.
bundle_id = _text(data.get("bundle_id"))
version = _text(data.get("version"))
if not bundle_id:
raise BundlerError(
"Corrupt records file: an installed-bundle record is missing "
"its 'bundle_id'."
)
if not version:
raise BundlerError(
f"Corrupt records file: record for bundle '{bundle_id}' is "
"missing its 'version'."
)
contributed = tuple(_component_from_dict(c) for c in components_raw)
required = tuple(
_component_from_dict(c, label="required") for c in required_raw
)
if not set(contributed).issubset(required):
raise BundlerError(
"Corrupt record: 'required_components' must include all "
"'contributed_components'."
)
installed_versions = data.get("installed_versions", {})
if not isinstance(installed_versions, dict):
raise BundlerError("Corrupt record: 'installed_versions' must be a mapping.")
bundle_references_raw = data.get("bundle_references")
if bundle_references_raw is None:
bundle_references: tuple[BundleRef, ...] = ()
elif not isinstance(bundle_references_raw, list):
raise BundlerError("Corrupt record: 'bundle_references' must be a list.")
else:
bundle_references = tuple(
_bundle_reference_from_dict(reference)
for reference in bundle_references_raw
)
keys = {f"{c.kind}:{c.id}" for c in required}
for key, actual in installed_versions.items():
if key not in keys or not isinstance(actual, str) or not actual.strip():
raise BundlerError(
"Corrupt record: 'installed_versions' must map required "
"component keys (kind:id) to non-empty version strings."
)
return cls(
bundle_id=bundle_id,
version=version,
installed_at=_text(data.get("installed_at")),
contributed_components=contributed,
required_components=required,
installed_versions=dict(installed_versions),
bundle_references=bundle_references,
)
def records_path(project_root: Path) -> Path:
return Path(project_root) / ".specify" / RECORDS_FILENAME
def _check_schema_version(value: Any, *, path: Path, required: bool) -> None:
"""Reject a records file whose schema version we cannot safely parse.
A future incompatible format (or a corrupted file) must fail fast with an
actionable error rather than being silently mis-parsed, which could lead to
incorrect bundle attribution or removal. Forward-compatible minor bumps that
keep the same major version are accepted.
"""
if value is None:
if required:
raise BundlerError(
f"Corrupt records file: {path} β missing 'schema_version'. "
f"Expected version {RECORDS_SCHEMA_VERSION}."
)
return
seen = str(value).strip()
if seen.split(".")[0] != RECORDS_SCHEMA_VERSION.split(".")[0]:
raise BundlerError(
f"Unsupported records schema version '{seen}' at {path}; this "
f"Spec Kit understands version {RECORDS_SCHEMA_VERSION}. The file may "
"have been written by a newer version or is corrupt."
)
def load_records(project_root: Path) -> list[InstalledBundleRecord]:
# Defense in depth (mirrors the write path's within= confinement): refuse to
# read through a symlinked or traversal-escaping ``.specify`` that resolves
# outside project_root.
path = ensure_within(project_root, records_path(project_root))
if not path.exists():
return []
data = load_json(path)
if not isinstance(data, dict):
raise BundlerError(f"Corrupt records file: {path}")
_check_schema_version(data.get("schema_version"), path=path, required=True)
bundles = data.get("bundles")
if bundles is None:
bundles = []
elif not isinstance(bundles, list):
# `or []` would coerce a FALSY non-list (0, '', False, {}) to [] before
# this guard, silently treating a corrupt file as "no bundles"; only an
# absent/None value means empty.
raise BundlerError(
f"Corrupt records file: {path} β 'bundles' must be a list."
)
return [InstalledBundleRecord.from_dict(item) for item in bundles]
def save_records(project_root: Path, records: list[InstalledBundleRecord]) -> None:
payload = {
"schema_version": RECORDS_SCHEMA_VERSION,
"updated_at": _utc_now(),
"bundles": [r.to_dict() for r in records],
}
dump_json(records_path(project_root), payload, within=project_root)
def find_record(
records: list[InstalledBundleRecord], bundle_id: str
) -> InstalledBundleRecord | None:
for record in records:
if record.bundle_id == bundle_id:
return record
return None
def upsert_record(
records: list[InstalledBundleRecord], record: InstalledBundleRecord
) -> list[InstalledBundleRecord]:
"""Return a new list with *record* replacing any same-id record (append otherwise)."""
updated = [r for r in records if r.bundle_id != record.bundle_id]
updated.append(record)
return updated
def remove_record(
records: list[InstalledBundleRecord], bundle_id: str
) -> list[InstalledBundleRecord]:
return [r for r in records if r.bundle_id != bundle_id]
def transfer_contributions(
records: list[InstalledBundleRecord],
released: list[ComponentRef] | tuple[ComponentRef, ...],
) -> list[InstalledBundleRecord]:
"""Keep a bundle-installed component attributed while another bundle needs it."""
updated = list(records)
owned = {
(component.kind, component.id)
for record in updated
for component in record.contributed_components
}
for component in released:
key = component.kind, component.id
if key in owned:
continue
for index, record in enumerate(updated):
required = next(
(
ref for ref in record.required_components
if (ref.kind, ref.id) == key
),
None,
)
if required is not None:
updated[index] = replace(
record,
contributed_components=(*record.contributed_components, required),
)
owned.add(key)
break
return updated
def components_still_needed(
records: list[InstalledBundleRecord], exclude_bundle_id: str
) -> set[tuple[str, str]]:
"""Set of ``(kind, id)`` component keys required by bundles other than the excluded one."""
needed: set[tuple[str, str]] = set()
for record in records:
if record.bundle_id == exclude_bundle_id:
continue
for component in record.required_components:
needed.add((component.kind, component.id))
return needed
def _component_to_dict(ref: ComponentRef) -> dict[str, Any]:
data: dict[str, Any] = {"kind": ref.kind, "id": ref.id}
if ref.version is not None:
data["version"] = ref.version
if ref.source is not None:
data["source"] = ref.source
if ref.priority is not None:
data["priority"] = ref.priority
if ref.strategy is not None:
data["strategy"] = ref.strategy
return data
def _bundle_reference_to_dict(reference: BundleRef) -> dict[str, Any]:
return {
"id": reference.id,
"version": reference.version,
"source": reference.source,
}
def _bundle_reference_from_dict(data: Any) -> BundleRef:
if not isinstance(data, dict):
raise BundlerError(
"Corrupt record: 'bundle_references' entries must be mappings."
)
bundle_id = data.get("id")
version = data.get("version")
if (
not isinstance(bundle_id, str)
or not bundle_id.strip()
or not isinstance(version, str)
or not version.strip()
):
raise BundlerError(
"Corrupt record: 'bundle_references' entries must have non-empty "
"string 'id' and 'version'."
)
source = data.get("source")
if source == "":
source = None
elif source is not None and not isinstance(source, str):
raise BundlerError(
"Corrupt record: 'bundle_references' entry 'source' must be a string."
)
return BundleRef(
id=bundle_id,
version=version,
source=source,
)
def _component_from_dict(data: Any, *, label: str = "contributed") -> ComponentRef:
if not isinstance(data, dict):
raise BundlerError(f"Each {label} component must be a mapping.")
kind = _text(data.get("kind"))
cid = _text(data.get("id"))
if kind not in COMPONENT_KINDS:
raise BundlerError(
f"Corrupt records file: component 'kind' must be one of "
f"{list(COMPONENT_KINDS)}, got {kind or '<missing>'!r}."
)
if not cid:
raise BundlerError(
f"Corrupt records file: a {label} component is missing its 'id'."
)
return ComponentRef(
kind=kind,
id=cid,
version=(str(data["version"]) if data.get("version") else None),
source=(str(data["source"]) if data.get("source") else None),
priority=_parse_priority(data.get("priority")),
strategy=(str(data["strategy"]) if data.get("strategy") else None),
)
def _parse_priority(raw: Any) -> int | None:
if raw is None:
return None
if isinstance(raw, bool) or not isinstance(raw, (int, str)):
raise BundlerError(f"Component priority must be an integer, got {raw!r}.")
try:
return int(raw)
except (TypeError, ValueError):
raise BundlerError(
f"Component priority must be an integer, got {raw!r}."
) from None
def _utc_now() -> str:
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")