π« Toolkit to help you get started with SDD or any other process!
"""Persistence for the project-scoped catalog config (``.specify/bundle-catalogs.yml``).
Only project scope is writable; built-in defaults are never deleted (they can be
overridden by adding a same-id source). The on-disk shape mirrors
``bundle-catalog.schema.md``: ``{schema_version, catalogs: [{id,url,priority,install_policy}]}``.
"""
from __future__ import annotations
from pathlib import Path
from urllib.parse import urlparse
import re
from . import BundlerError
from .yamlio import dump_yaml, ensure_within, load_yaml
from .catalogs import (
CONFIG_FILENAME,
CONFIG_SCHEMA_VERSION,
BUILTIN_DEFAULT_STACK,
CatalogSource,
InstallPolicy,
Scope,
)
_BUILTIN_IDS = {raw["id"] for raw in BUILTIN_DEFAULT_STACK}
# Windows absolute paths like ``C:\catalog.json`` parse with a single-letter
# ``scheme`` under urlparse; treat them as local files rather than URLs.
_WINDOWS_DRIVE_RE = re.compile(r"^[A-Za-z]:[\\/]")
def _config_path(project_root: Path) -> Path:
return Path(project_root) / ".specify" / CONFIG_FILENAME
def _read(project_root: Path) -> list[dict]:
# Confine the read (parity with the write path's within= guard): refuse to
# follow a symlinked or traversal-escaping .specify that resolves outside
# project_root.
path = ensure_within(project_root, _config_path(project_root))
if not path.exists():
return []
# ``load_yaml`` returns ``{}`` only for an empty document and the raw parse
# otherwise, so a non-mapping top level β a falsy ``[]``/``false``/``0``/``''``
# or an explicit null (``load_yaml`` -> ``None``) β is caught by the isinstance
# guard below and raised like a truthy one, staying consistent with the other
# reader of this file (models/catalog._merge_config).
data = load_yaml(path)
if not isinstance(data, dict):
raise BundlerError(
f"Malformed catalog config at {path}: expected a mapping at the top "
f"level, got {type(data).__name__}."
)
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 {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):
raise BundlerError(
f"Malformed catalog config at {path}: 'catalogs' must be a list, "
f"got {type(catalogs).__name__}."
)
for entry in catalogs:
if not isinstance(entry, dict):
raise BundlerError(
f"Malformed catalog config at {path}: each catalog entry must be "
f"a mapping, got {type(entry).__name__}."
)
return list(catalogs)
def _write(project_root: Path, catalogs: list[dict]) -> None:
payload = {"schema_version": CONFIG_SCHEMA_VERSION, "catalogs": catalogs}
dump_yaml(_config_path(project_root), payload, within=project_root)
def _slug(value: str) -> str:
# Lowercase so derived ids are deterministic and case-insensitive across
# platforms (e.g. 'Team-A.json' and 'team-a.json' yield the same id),
# keeping the case-sensitive duplicate check from admitting logical dupes.
return "".join(ch if ch.isalnum() else "-" for ch in value.lower()).strip("-")
_REMOTE_SCHEMES = {"http", "https", "file", "builtin"}
def _is_local_path(url: str) -> bool:
"""True when *url* denotes a local filesystem path rather than a URL."""
if _WINDOWS_DRIVE_RE.match(url):
return True
try:
scheme = urlparse(url).scheme.lower()
except ValueError:
# Malformed URLs (e.g. an unclosed IPv6 bracket) are not local paths.
return False
return scheme not in _REMOTE_SCHEMES
def _canonicalize_url(url: str) -> str:
"""Make local file paths absolute so config is independent of the caller's cwd.
Remote URLs (``http(s)://``, ``file://``, ``builtin://``) are returned
unchanged; only bare/relative local paths are resolved to an absolute path.
"""
if _is_local_path(url):
return str(Path(url).expanduser().resolve())
return url
def _derive_id(url: str) -> str:
parsed = urlparse(url)
if parsed.netloc:
# Use .hostname (not netloc.split(':')) so credentials, ports, and IPv6
# literals (e.g. https://[2001:db8::1]/x) are handled correctly. Use the
# full host (TLD included) so different domains sharing a second-level
# label (example.com vs example.net) don't collide. _slug() lowercases
# and turns separators into dashes, so 'Example.com' -> 'example-com'.
host = parsed.hostname or ""
path_stem = Path(parsed.path).stem if parsed.path else ""
parts = [p for p in (_slug(host), _slug(path_stem)) if p]
return "-".join(parts) or "catalog"
stem = Path(parsed.path or url).stem
return _slug(stem) or "catalog"
def add_source(
project_root: Path,
url: str,
*,
policy: str,
priority: int,
source_id: str | None = None,
) -> tuple[CatalogSource, str]:
url = url.strip()
if not url:
raise BundlerError("A catalog url is required.")
try:
parsed = urlparse(url)
# Read .hostname inside the try: a bracketed-but-invalid IPv6 authority
# (e.g. "https://[not-an-ip]/c.json") parses cleanly under urlparse() on
# Python < 3.14 but raises ValueError lazily on the first .hostname access
# (the raise moved eager into urlparse() only in 3.14). Reading it here
# keeps that ValueError inside the guard instead of leaking a raw
# traceback past the CLI's `except BundlerError`. Reuse the value below.
hostname = parsed.hostname
# Accessing ``port`` performs urllib's syntax/range validation.
_ = parsed.port
except ValueError as exc:
raise BundlerError(f"Invalid catalog url: '{url}'.") from exc
if not (parsed.scheme or parsed.path):
raise BundlerError(f"Invalid catalog url: '{url}'.")
# Reject unsupported URL schemes (e.g. ssh://, ftp://) up front so they are
# never silently canonicalized as local filesystem paths. Local paths that
# merely contain a ':' but no '://' (e.g. Windows drives) are still allowed.
if "://" in url and parsed.scheme.lower() not in _REMOTE_SCHEMES:
raise BundlerError(
f"Unsupported catalog url scheme '{parsed.scheme}://' in '{url}'. "
"Use http(s)://, file://, builtin://, or a local path."
)
if parsed.scheme.lower() in {"http", "https"}:
# Mirror specify_cli.catalogs._validate_catalog_url (#3209/#3210):
# HTTPS only (HTTP just for localhost), and check hostname, not
# netloc β netloc is truthy for host-less URLs like "https://:8080"
# or "https://user@". Validating here keeps junk out of
# bundle-catalogs.yml instead of failing later at fetch time.
is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
if parsed.scheme.lower() != "https" and not is_localhost:
raise BundlerError(
f"Catalog url must use HTTPS (got {parsed.scheme}://). "
"HTTP is only allowed for localhost."
)
if not hostname:
raise BundlerError(f"Catalog url must be a valid URL with a host: {url}")
url = _canonicalize_url(url)
install_policy = InstallPolicy.parse(policy)
requested_id = source_id.strip() if source_id is not None else ""
resolved_id = requested_id or _derive_id(url)
catalogs = _read(project_root)
requested_source = CatalogSource.from_dict(
{
"id": resolved_id,
"url": url,
"priority": priority,
"install_policy": install_policy.value,
},
Scope.PROJECT,
)
id_collision = False
for existing in catalogs:
existing_source = CatalogSource.from_dict(existing, Scope.PROJECT)
if existing_source.url == requested_source.url:
if (
(not requested_id or existing_source.id == requested_source.id)
and existing_source.priority == requested_source.priority
and existing_source.install_policy is requested_source.install_policy
):
return existing_source, "unchanged"
raise BundlerError(
f"Catalog source '{resolved_id}' (or url) already exists in this project."
)
if existing_source.id == requested_source.id:
id_collision = True
if id_collision:
raise BundlerError(
f"Catalog source '{resolved_id}' (or url) already exists in this project."
)
entry = requested_source.to_dict()
catalogs.append(entry)
_write(project_root, catalogs)
return requested_source, "added"
def remove_source(project_root: Path, id_or_url: str) -> str:
target = id_or_url.strip()
catalogs = _read(project_root)
# Refuse a built-in id only when there is nothing project-scoped to remove.
# This message tells the user to "add a same-id source to override it" --
# and once they did, the same guard refused to delete that override, so the
# documented workflow had no way back short of hand-editing the config.
# A project-scoped entry is the user's own file and is theirs to remove;
# deleting it simply restores the built-in default.
if target in _BUILTIN_IDS and not any(c.get("id") == target for c in catalogs):
raise BundlerError(
f"'{target}' is a built-in default source and cannot be deleted "
"(add a same-id source to override it instead)."
)
# Prefer an exact id/url match.
remaining = [c for c in catalogs if c.get("id") != target and c.get("url") != target]
if len(remaining) == len(catalogs):
# No exact match. add_source canonicalizes a local path to an absolute
# url before storing, so fall back to a canonicalized-url match -- this
# lets `remove ./cat.json` undo `add ./cat.json` (stored absolute).
# Only as a *fallback*: _canonicalize_url treats a bare id as a local
# path (empty scheme), so applying it unconditionally could also delete a
# different source whose url equals the id's canonicalized path.
canonical = _canonicalize_url(target)
if canonical != target:
remaining = [c for c in catalogs if c.get("url") != canonical]
if len(remaining) == len(catalogs):
raise BundlerError(
f"No project-scoped catalog source matching '{target}' was found."
)
_write(project_root, remaining)
return target