π« Toolkit to help you get started with SDD or any other process!
refactor(presets): split domain internals into private modules (#4747)
Manfred Riemab80b144bf7a
diff --git a/design/cli.md b/design/cli.mdindex 0829df74f..b38dfec09 100644--- a/design/cli.md+++ b/design/cli.md@@ -249,6 +249,25 @@ the domain has the same name as that CLI namespace. The nested directory isreserved for `test_command_<name>.py` suites that exercise its actualsubcommands.+When a domain implementation is split into private modules, mirror those+boundaries in its tests, dropping the source module's leading underscore:++| Preset implementation | Mirrored test under `tests/specify_cli/presets/` |+| --- | --- |+| `_manifest.py` | `test_manifest.py` |+| `_registry.py` | `test_registry.py` |+| `_catalog.py` | `test_catalog.py` |+| `_resolver.py` | `test_resolver.py` |+| `_manager.py` | `test_manager.py` |+| `_manager_commands.py` | `test_manager_commands.py` |+| `_manager_skills.py` | `test_manager_skills.py` |++`test_manager_commands.py` exercises domain command-artifact behavior, not a+registered CLI handler. The `test_command_*.py` suites continue to cover the+CLI surface. `test_catalog.py` belongs at the parent preset package level;+`catalog/test_command_*.py` covers the nested catalog CLI. Package export+compatibility is covered separately by `test_domain_exports.py`.+Not every test is a command test, even when it belongs in the mirrored packagetree:@@ -264,6 +283,10 @@ tree:Moving tests must preserve coverage rather than duplicating it. Run both thenew command-focused suites and the legacy suites from which tests were moved.+For domain splits, also run all new domain suites and any remaining cross-domain+tests in the legacy file. Compare full-suite collection before and after the+move: the count must not decrease, and every existing parametrized test case+must remain represented. A matching total alone does not prove preservation.## Reference layoutdiff --git a/src/specify_cli/presets/__init__.py b/src/specify_cli/presets/__init__.pyindex eff1e6815..2d325530f 100644--- a/src/specify_cli/presets/__init__.py+++ b/src/specify_cli/presets/__init__.py@@ -1,6259 +1,64 @@-"""-Preset Manager for Spec Kit+"""Preset domain exports; ``_commands.py`` registers the CLI handlers.-Handles installation, removal, and management of Spec Kit presets.-Presets are self-contained, versioned collections of templates-(artifact, command, and script templates) that can be installed to-customize the Spec-Driven Development workflow.+Handlers live in ``command_*.py`` and ``catalog/``. Domain implementations+live in private modules; package-level names preserve existing internal imports."""-import copy-import json-import hashlib-import os-import tempfile-import shutil-from dataclasses import dataclass-from pathlib import Path-from typing import TYPE_CHECKING, Optional, Dict, List, Any, Union, Set--if TYPE_CHECKING:- from ..agents import CommandRegistrar-from datetime import datetime, timezone-import re--import yaml-from packaging import version as pkg_version-from packaging.specifiers import SpecifierSet, InvalidSpecifier-from .._download_security import (- archive_format_from_name,- archive_suffix,- MAX_JSON_CATALOG_BYTES,- build_safe_download_path,- detect_archive_format,- is_https_or_localhost_http,- read_response_limited,- safe_extract_archive,+ MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES,)-from ..extensions import REINSTALL_COMMAND, ExtensionRegistry, normalize_priority-from .._init_options import (- MISSING_INIT_OPTIONS_FILE,- is_ai_skills_enabled,- load_init_options,- resolve_active_agent_for_registration,+from .._download_security import (+ read_response_limited as read_response_limited,)-from .._invocation_style import get_invocation_prefix-from ..integrations.base import IntegrationBase-from .._utils import dump_frontmatter, version_satisfies-from ..shared_infra import (- _ensure_safe_shared_destination,- _ensure_safe_shared_directory,- _write_shared_bytes,- _write_shared_text,- verify_archive_sha256,+from ..extensions import ExtensionRegistry as ExtensionRegistry+from ..shared_infra import verify_archive_sha256 as verify_archive_sha256+from ._catalog import PresetCatalog as PresetCatalog+from ._catalog import PresetCatalogEntry as PresetCatalogEntry+from ._manager import (+ _CONSTITUTION_PROVENANCE_FILE as _CONSTITUTION_PROVENANCE_FILE,)---_CONSTITUTION_PROVENANCE_FILE = ".constitution-template.json"-_CONSTITUTION_SYNC_PRESET_ID = "constitution-sync"---def _content_sha256(content: bytes) -> str:- return hashlib.sha256(content).hexdigest()---def _is_comparable_version(value: str) -> bool:- """Return whether a recorded version can be evaluated against a specifier.-- ``version_satisfies()`` answers "does not satisfy" for an unparseable- version, which is indistinguishable from a genuine mismatch. Callers that- need to tell those apart check here first.- """- try:- pkg_version.Version(value)- except pkg_version.InvalidVersion:- return False- return True---def _constitution_is_generated(- project_root: Path,- memory_constitution: Path,- resolver: "PresetResolver",-) -> bool:- """Return whether the live constitution is an unchanged generated file."""- _ensure_safe_shared_destination(project_root, memory_constitution)- content = memory_constitution.read_bytes()- provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE- _ensure_safe_shared_destination(project_root, provenance)-- if provenance.exists():- try:- metadata = json.loads(provenance.read_text(encoding="utf-8"))- except (json.JSONDecodeError, UnicodeDecodeError):- return False- return (- isinstance(metadata, dict)- and metadata.get("sha256") == _content_sha256(content)- )-- # Older projects have no provenance sidecar. Only the immutable bundled or- # source-checkout core template is safe to treat as generated.- core = resolver._find_bundled_core(- "constitution-template", "template", ".md"- )- return core is not None and core.read_bytes() == content---def _constitution_provenance_matches_preset(- project_root: Path,- memory_constitution: Path,- pack_id: str,- pack_version: str,-) -> bool:- """Return whether provenance identifies a preset as the materialized source."""- provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE- if not provenance.parent.exists():- return False- _ensure_safe_shared_destination(project_root, provenance)- if not provenance.exists():- return False- try:- metadata = json.loads(provenance.read_text(encoding="utf-8"))- except (OSError, json.JSONDecodeError, UnicodeDecodeError):- return False- return (- isinstance(metadata, dict)- and metadata.get("source") == f"{pack_id} v{pack_version}"- )---def _materialize_constitution_template(- project_root: Path,- memory_constitution: Path,-) -> str | None:- """Materialize constitution-template content into memory/constitution.md.-- Returns:- "copied" when the winning layer is ``replace`` and the source file is- copied verbatim; "composed" when a composing strategy is materialized- via ``resolve_content``; ``None`` when no constitution template resolves.- """- resolver = PresetResolver(project_root)- layers = resolver.collect_all_layers("constitution-template", "template")- if not layers:- return None-- top_layer = layers[0]- if top_layer["strategy"] == "replace":- content = top_layer["path"].read_bytes()- result = "copied"- else:- composed_content = resolver.resolve_content("constitution-template", "template")- if composed_content is None:- return None- content = composed_content.encode("utf-8")- result = "composed"-- _ensure_safe_shared_directory(project_root, memory_constitution.parent)- _write_shared_bytes(project_root, memory_constitution, content)- provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE- _write_shared_text(- project_root,- provenance,- json.dumps(- {- "sha256": _content_sha256(content),- "source": top_layer["source"],- },- indent=2,- )- + "\n",- )- return result---def _substitute_core_template(- body: str,- cmd_name: str,- project_root: "Path",- registrar: "CommandRegistrar",-) -> "tuple[str, dict]":- """Substitute {CORE_TEMPLATE} with the body of the installed core command template.-- Args:- body: Preset command body (may contain {CORE_TEMPLATE} placeholder).- cmd_name: Full command name (e.g. "speckit.git.feature" or "speckit.specify").- project_root: Project root path.- registrar: CommandRegistrar instance for parse_frontmatter.-- Returns:- A tuple of (body, core_frontmatter) where body has {CORE_TEMPLATE} replaced- by the core template body and core_frontmatter holds the core template's parsed- frontmatter (so callers can inherit scripts/agent_scripts from it). Both are- unchanged / empty when the placeholder is absent or the core template file does- not exist or cannot be read.- """- if "{CORE_TEMPLATE}" not in body:- return body, {}-- # Derive the short name (strip "speckit." prefix) used by core command templates.- short_name = cmd_name- if short_name.startswith("speckit."):- short_name = short_name[len("speckit."):]-- resolver = PresetResolver(project_root)- # Resolution order for the core template:- # 1. resolve_core(cmd_name) β covers tier-1 project overrides and tier-3/4- # name-based lookup (file named <cmd_name>.md). Checked first so that a- # local override always wins, even for extension commands.- # 2. resolve_extension_command_via_manifest(cmd_name) β manifest-based tier-3- # fallback for extension commands whose file is named differently from the- # command name (e.g. speckit.selftest.extension β commands/selftest.md).- # 3. resolve_core(short_name) β core template fallback using the unprefixed- # name (e.g. specify β templates/commands/specify.md).- # resolve_core() skips installed presets (tier 2) to prevent accidental nesting- # where another preset's wrap output is mistaken for the real core.- core_file = (- resolver.resolve_core(cmd_name, "command")- or resolver.resolve_extension_command_via_manifest(cmd_name)- or resolver.resolve_core(short_name, "command")- )- if core_file is None:- return body, {}-- # Treat an unreadable/undecodable core template like a missing one so a- # single corrupted project override cannot crash command registration β- # the wrap-strategy callers already skip an unreadable preset source with- # a warning (CommandRegistrar.register_pack).- try:- core_content = core_file.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError) as exc:- import warnings-- warnings.warn(- f"Ignoring core template for command '{cmd_name}': could not read "- f"'{core_file.name}' ({exc.__class__.__name__}: {exc}).",- stacklevel=2,- )- return body, {}-- core_frontmatter, core_body = registrar.parse_frontmatter(core_content)- return body.replace("{CORE_TEMPLATE}", core_body), core_frontmatter---@dataclass-class PresetCatalogEntry:- """Represents a single entry in the preset catalog stack."""- url: str- name: str- priority: int- install_allowed: bool- description: str = ""---class PresetError(Exception):- """Base exception for preset-related errors."""- pass---class PresetValidationError(PresetError):- """Raised when preset manifest validation fails."""- pass---class PresetCompatibilityError(PresetError):- """Raised when preset is incompatible with current environment."""- pass---VALID_PRESET_TEMPLATE_TYPES = {"template", "command", "script"}-VALID_PRESET_STRATEGIES = {"replace", "prepend", "append", "wrap"}-# Scripts only support replace and wrap (prepend/append don't make semantic sense for executable code)-VALID_SCRIPT_STRATEGIES = {"replace", "wrap"}---class PresetManifest:- """Represents and validates a preset manifest (preset.yml)."""-- SCHEMA_VERSION = "1.0"- REQUIRED_FIELDS = ["schema_version", "preset", "requires", "provides"]-- def __init__(self, manifest_path: Path):- """Load and validate preset manifest.-- Args:- manifest_path: Path to preset.yml file-- Raises:- PresetValidationError: If manifest is invalid- """- self.path = manifest_path- self.data = self._load_yaml(manifest_path)- self._validate()-- def _load_yaml(self, path: Path) -> dict:- """Load YAML file safely."""- try:- with open(path, 'r', encoding='utf-8') as f:- data = yaml.safe_load(f)- except yaml.YAMLError as e:- raise PresetValidationError(f"Invalid YAML in {path}: {e}")- except FileNotFoundError:- raise PresetValidationError(f"Manifest not found: {path}")- except UnicodeDecodeError as e:- raise PresetValidationError(- f"Manifest is not valid UTF-8: {path} ({e.reason} at byte {e.start})"- )- except OSError as e:- raise PresetValidationError(f"Could not read manifest {path}: {e}")- if data is None:- return {}- if not isinstance(data, dict):- raise PresetValidationError(- f"Manifest must be a YAML mapping, got {type(data).__name__}: {path}"- )- return data-- def _validate(self):- """Validate manifest structure and required fields."""- # Check required top-level fields- for field in self.REQUIRED_FIELDS:- if field not in self.data:- raise PresetValidationError(f"Missing required field: {field}")-- # Validate schema version- if self.data["schema_version"] != self.SCHEMA_VERSION:- raise PresetValidationError(- f"Unsupported schema version: {self.data['schema_version']} "- f"(expected {self.SCHEMA_VERSION})"- )-- for section in ("preset", "requires", "provides"):- if not isinstance(self.data[section], dict):- raise PresetValidationError(- f"Invalid {section}: expected a mapping"- )-- # Validate preset metadata- pack = self.data["preset"]- # Check presence AND type: the format/version checks below feed these- # values straight to ``re.match`` and ``packaging.Version``, both of- # which raise a bare TypeError on a non-string. YAML makes that an easy- # authoring slip -- unquoted ``version: 1.0`` parses as a float and- # ``id: 2`` as an int -- and TypeError is not a PresetValidationError,- # so it escapes every caller that already handles a malformed manifest- # (see list_installed()'s "Corrupted preset" fallback, which catches- # PresetValidationError only, making one bad preset exit ``specify- # preset list`` with a raw traceback and hide the healthy ones).- # Mirrors the sibling IntegrationDescriptor, which already type-checks- # the same four fields.- for field in ["id", "name", "version", "description"]:- if field not in pack:- raise PresetValidationError(f"Missing preset.{field}")- if not isinstance(pack[field], str):- raise PresetValidationError(- f"Invalid preset.{field}: expected a string, "- f"got {type(pack[field]).__name__}"- )-- # Validate pack ID format- if not re.match(r'^[a-z0-9-]+$', pack["id"]):- raise PresetValidationError(- f"Invalid preset ID '{pack['id']}': "- "must be lowercase alphanumeric with hyphens only"- )-- # Validate semantic version- try:- pkg_version.Version(pack["version"])- except pkg_version.InvalidVersion:- raise PresetValidationError(f"Invalid version: {pack['version']}")-- # Validate requires section- requires = self.data["requires"]- if "speckit_version" not in requires:- raise PresetValidationError("Missing requires.speckit_version")- # Presence alone is not enough: check_compatibility() feeds this value to- # ``SpecifierSet(required)``, guarded only by ``except InvalidSpecifier``,- # which a non-string escapes two different ways. A float/int/bool/None- # raises TypeError from the constructor, while a list or dict is an- # *iterable*, so SpecifierSet accepts it and the failure surfaces much- # later as ``AttributeError: 'str' object has no attribute 'filter'`` from- # inside .contains(). Neither is a PresetCompatibilityError, so both- # bypass the CLI's "Compatibility Error" handler and exit 1 with a raw- # traceback naming no field. An unquoted ``speckit_version: 1.0`` is an- # easy YAML slip. Mirrors the sibling IntegrationDescriptor, which already- # requires a non-empty string here.- if (- not isinstance(requires["speckit_version"], str)- or not requires["speckit_version"].strip()- ):- raise PresetValidationError(- "Invalid requires.speckit_version: expected a non-empty string, "- f"got {type(requires['speckit_version']).__name__}"- )-- # Validate the optional extension dependency list. A preset that- # overrides commands calling into an extension is inert without it, and- # until now the only place that could be said was the README -- see- # issue #4231. Absent means "no dependencies", so every existing preset- # stays valid.- if "extensions" in requires:- self._validate_requires_extensions(requires["extensions"])-- # Validate provides section- provides = self.data["provides"]- if "templates" not in provides:- raise PresetValidationError(- "Preset must provide at least one template"- )-- # Validate templates. Guard the container and each entry's shape so a- # malformed third-party preset.yml (e.g. ``templates: 5`` or- # ``templates: [null]``) raises a clean PresetValidationError the- # install handler already catches, instead of a raw TypeError- # ('int'/'NoneType' object is not iterable) that escapes to an- # unhandled traceback. Mirrors the sibling ExtensionManifest guards.- #- # Order matters: the container's TYPE is checked before its emptiness,- # so a FALSY non-list (``templates: 0``/``false``/``null``/``''``/``{}``)- # reports the accurate type error rather than the misleading "must- # provide at least one template". An empty list still reports the- # latter, since that genuinely is a list with no templates.- templates = provides["templates"]- if not isinstance(templates, list):- raise PresetValidationError(- "Invalid provides.templates: expected a list"- )- if not templates:- raise PresetValidationError(- "Preset must provide at least one template"- )- seen_name_types: set[tuple[str, str]] = set()- for tmpl in templates:- if not isinstance(tmpl, dict):- raise PresetValidationError(- "Each template entry in 'provides.templates' must be a mapping"- )- if "type" not in tmpl or "name" not in tmpl or "file" not in tmpl:- raise PresetValidationError(- "Template missing 'type', 'name', or 'file'"- )-- # 'name' feeds re.match and 'file' feeds os.path.normpath below;- # both raise a bare TypeError on a non-string, which is not a- # PresetValidationError and so escapes the callers that handle a- # malformed manifest. The sibling extension manifest already- # rejects a non-string command 'file' via- # relative_extension_path_violation().- for field in ("type", "name", "file"):- if not isinstance(tmpl[field], str):- raise PresetValidationError(- f"Invalid template {field}: expected a string, "- f"got {type(tmpl[field]).__name__}"- )-- if tmpl["type"] not in VALID_PRESET_TEMPLATE_TYPES:- raise PresetValidationError(- f"Invalid template type '{tmpl['type']}': "- f"must be one of {sorted(VALID_PRESET_TEMPLATE_TYPES)}"- )-- # PresetResolver._manifest_declared_template returns the first- # 'provides.templates' entry matching a given (name, type) pair, so- # a later duplicate would be silently unreachable while still being- # counted by PresetManifest.templates. Reject at validation time- # instead, mirroring the sibling fix for ExtensionManifest's- # provides.templates/scripts (#4016).- name_type = (tmpl["name"], tmpl["type"])- if name_type in seen_name_types:- raise PresetValidationError(- f"Duplicate template name '{tmpl['name']}' of type "- f"'{tmpl['type']}' in 'provides.templates'"- )- seen_name_types.add(name_type)-- # Validate file path safety: must be relative, no parent traversal- file_path = tmpl["file"]- normalized = os.path.normpath(file_path)- if os.path.isabs(normalized) or normalized.startswith(".."):- raise PresetValidationError(- f"Invalid template file path '{file_path}': "- "must be a relative path within the preset directory"- )-- # Validate strategy field (optional, defaults to "replace")- strategy = tmpl.get("strategy", "replace")- if not isinstance(strategy, str):- raise PresetValidationError(- f"Invalid strategy value: must be a string, "- f"got {type(strategy).__name__}"- )- strategy = strategy.lower()- # Persist normalized value so downstream code sees lowercase- if "strategy" in tmpl:- tmpl["strategy"] = strategy- if strategy not in VALID_PRESET_STRATEGIES:- raise PresetValidationError(- f"Invalid strategy '{strategy}': "- f"must be one of {sorted(VALID_PRESET_STRATEGIES)}"- )- if tmpl["type"] == "script" and strategy not in VALID_SCRIPT_STRATEGIES:- raise PresetValidationError(- f"Invalid strategy '{strategy}' for script: "- f"scripts only support {sorted(VALID_SCRIPT_STRATEGIES)}"- )-- # Validate template name format- if tmpl["type"] == "command":- # Commands use dot notation (e.g. speckit.specify)- if not re.match(r'^[a-z0-9.-]+$', tmpl["name"]):- raise PresetValidationError(- f"Invalid command name '{tmpl['name']}': "- "must be lowercase alphanumeric with hyphens and dots only"- )- else:- if not re.match(r'^[a-z0-9-]+$', tmpl["name"]):- raise PresetValidationError(- f"Invalid template name '{tmpl['name']}': "- "must be lowercase alphanumeric with hyphens only"- )-- @property- def id(self) -> str:- """Get preset ID."""- return self.data["preset"]["id"]-- @property- def name(self) -> str:- """Get preset name."""- return self.data["preset"]["name"]-- @property- def version(self) -> str:- """Get preset version."""- return self.data["preset"]["version"]-- @property- def description(self) -> str:- """Get preset description."""- return self.data["preset"]["description"]-- @property- def author(self) -> str:- """Get preset author."""- return self.data["preset"].get("author", "")-- @staticmethod- def _validate_requires_extensions(declared: Any) -> None:- """Validate the optional ``requires.extensions`` list.-- Accepts either a bare extension id or a mapping carrying an optional- version specifier and an optional ``required`` flag:-- .. code-block:: yaml-- requires:- extensions:- - speckit-inventory- - id: other-ext- version: ">=1.2.0"- required: false-- Raises:- PresetValidationError: If the list or any entry is malformed.- """- if not isinstance(declared, list):- raise PresetValidationError(- "Invalid requires.extensions: expected a list, "- f"got {type(declared).__name__}"- )-- for index, entry in enumerate(declared):- label = f"requires.extensions[{index}]"-- if isinstance(entry, str):- entry = {"id": entry}- elif not isinstance(entry, dict):- raise PresetValidationError(- f"Invalid {label}: expected a string or a mapping, "- f"got {type(entry).__name__}"- )-- if "id" not in entry:- raise PresetValidationError(f"Missing {label}.id")- extension_id = entry["id"]- if not isinstance(extension_id, str):- raise PresetValidationError(- f"Invalid {label}.id: expected a string, "- f"got {type(extension_id).__name__}"- )- # Same id shape the extension loader enforces, so a dependency can- # never name something that could not be installed in the first- # place. fullmatch rather than match with an anchored pattern: `$`- # also matches before a trailing newline, so "demo-ext\n" would- # otherwise validate here while PresetResolver._is_safe_registry_id- # (which uses fullmatch) rejects it, and the newline would land in- # a suggested command.- if not re.fullmatch(r'[a-z0-9-]+', extension_id):- raise PresetValidationError(- f"Invalid {label}.id {extension_id!r}: "- "must be lowercase alphanumeric with hyphens only"- )-- if "version" in entry:- constraint = entry["version"]- # Mirrors the requires.speckit_version reasoning: a non-string- # escapes InvalidSpecifier two ways -- scalars raise TypeError- # from the constructor, and a list/dict is iterable so it- # constructs and only fails later inside .contains().- if not isinstance(constraint, str) or not constraint.strip():- raise PresetValidationError(- f"Invalid {label}.version: expected a non-empty string, "- f"got {type(constraint).__name__}"- )- try:- SpecifierSet(constraint)- except InvalidSpecifier:- raise PresetValidationError(- f"Invalid {label}.version '{constraint}': "- "not a valid version specifier"- )-- if "required" in entry and not isinstance(entry["required"], bool):- raise PresetValidationError(- f"Invalid {label}.required: expected a boolean, "- f"got {type(entry['required']).__name__}"- )-- @property- def requires_speckit_version(self) -> str:- """Get required spec-kit version range."""- return self.data["requires"]["speckit_version"]-- @property- def requires_extensions(self) -> List[Dict[str, Any]]:- """Get declared extension dependencies, normalized to mappings.-- Returns:- One entry per dependency with ``id``, ``version`` (``None`` when- unconstrained), and ``required`` (defaulting to ``True``). Empty- when the manifest declares no dependencies.- """- declared = self.data["requires"].get("extensions")- if not isinstance(declared, list):- return []-- normalized: List[Dict[str, Any]] = []- for entry in declared:- if isinstance(entry, str):- entry = {"id": entry}- if not isinstance(entry, dict) or not isinstance(entry.get("id"), str):- continue- normalized.append(- {- "id": entry["id"],- "version": entry.get("version"),- "required": entry.get("required", True),- }- )- return normalized-- @property- def templates(self) -> List[Dict[str, Any]]:- """Get list of provided templates."""- return self.data["provides"]["templates"]-- @property- def tags(self) -> List[str]:- """Get preset tags."""- return self.data.get("tags", [])-- def get_hash(self) -> str:- """Calculate SHA256 hash of manifest file."""- h = hashlib.sha256()- with open(self.path, 'rb') as f:- for chunk in iter(lambda: f.read(8192), b""):- h.update(chunk)- return f"sha256:{h.hexdigest()}"---class PresetRegistry:- """Manages the registry of installed presets."""-- REGISTRY_FILE = ".registry"- SCHEMA_VERSION = "1.0"-- def __init__(self, packs_dir: Path):- """Initialize registry.-- Args:- packs_dir: Path to .specify/presets/ directory- """- self.packs_dir = packs_dir- self.registry_path = packs_dir / self.REGISTRY_FILE- self.data = self._load()-- def _load(self) -> dict:- """Load registry from disk."""- if not self.registry_path.exists():- return {- "schema_version": self.SCHEMA_VERSION,- "presets": {}- }-- try:- with open(self.registry_path, 'r', encoding='utf-8') as f:- data = json.load(f)- # Validate loaded data is a dict (handles corrupted registry files)- if not isinstance(data, dict):- return {- "schema_version": self.SCHEMA_VERSION,- "presets": {}- }- # Normalize presets field (handles corrupted presets value)- if not isinstance(data.get("presets"), dict):- data["presets"] = {}- return data- except (json.JSONDecodeError, UnicodeDecodeError, FileNotFoundError):- # Corrupted or missing registry, start fresh. A registry whose- # bytes cannot be decoded as UTF-8 is the same corruption class- # as malformed JSON β only the exception type differs. OSError is- # deliberately not caught: the data may be intact on disk, and- # starting fresh would let a later _save() wipe it.- return {- "schema_version": self.SCHEMA_VERSION,- "presets": {}- }-- def _save(self):- """Save registry to disk."""- self.packs_dir.mkdir(parents=True, exist_ok=True)- with open(self.registry_path, 'w', encoding='utf-8') as f:- json.dump(self.data, f, indent=2)-- def add(self, pack_id: str, metadata: dict):- """Add preset to registry.-- Args:- pack_id: Preset ID- metadata: Pack metadata (version, source, etc.)- """- self.data["presets"][pack_id] = {- **copy.deepcopy(metadata),- "installed_at": datetime.now(timezone.utc).isoformat()- }- self._save()-- def remove(self, pack_id: str):- """Remove preset from registry.-- Args:- pack_id: Preset ID- """- packs = self.data.get("presets")- if not isinstance(packs, dict):- return- if pack_id in packs:- del packs[pack_id]- self._save()-- def update(self, pack_id: str, updates: dict):- """Update preset metadata in registry.-- Merges the provided updates with the existing entry, preserving any- fields not specified. The installed_at timestamp is always preserved- from the original entry.-- Args:- pack_id: Preset ID- updates: Partial metadata to merge into existing metadata-- Raises:- KeyError: If preset is not installed- """- packs = self.data.get("presets")- if not isinstance(packs, dict) or pack_id not in packs:- raise KeyError(f"Preset '{pack_id}' not found in registry")- existing = packs[pack_id]- # Handle corrupted registry entries (e.g., string/list instead of dict)- if not isinstance(existing, dict):- existing = {}- # Merge: existing fields preserved, new fields override (deep copy to prevent caller mutation)- merged = {**existing, **copy.deepcopy(updates)}- # Always preserve original installed_at based on key existence, not truthiness,- # to handle cases where the field exists but may be falsy (legacy/corruption)- if "installed_at" in existing:- merged["installed_at"] = existing["installed_at"]- else:- # If not present in existing, explicitly remove from merged if caller provided it- merged.pop("installed_at", None)- packs[pack_id] = merged- self._save()-- def restore(self, pack_id: str, metadata: dict):- """Restore preset metadata to registry without modifying timestamps.-- Use this method for rollback scenarios where you have a complete backup- of the registry entry (including installed_at) and want to restore it- exactly as it was.-- Args:- pack_id: Preset ID- metadata: Complete preset metadata including installed_at-- Raises:- ValueError: If metadata is None or not a dict- """- if metadata is None or not isinstance(metadata, dict):- raise ValueError(f"Cannot restore '{pack_id}': metadata must be a dict")- # Ensure presets dict exists (handle corrupted registry)- if not isinstance(self.data.get("presets"), dict):- self.data["presets"] = {}- self.data["presets"][pack_id] = copy.deepcopy(metadata)- self._save()-- def get(self, pack_id: str) -> Optional[dict]:- """Get preset metadata from registry.-- Returns a deep copy to prevent callers from accidentally mutating- nested internal registry state without going through the write path.-- Args:- pack_id: Preset ID-- Returns:- Deep copy of preset metadata, or None if not found or corrupted- """- packs = self.data.get("presets")- if not isinstance(packs, dict):- return None- entry = packs.get(pack_id)- # Return None for missing or corrupted (non-dict) entries- if entry is None or not isinstance(entry, dict):- return None- return copy.deepcopy(entry)-- def list(self) -> Dict[str, dict]:- """Get all installed presets with valid metadata.-- Returns a deep copy of presets with dict metadata only.- Corrupted entries (non-dict values) are filtered out.-- Returns:- Dictionary of pack_id -> metadata (deep copies), empty dict if corrupted- """- packs = self.data.get("presets", {}) or {}- if not isinstance(packs, dict):- return {}- # Filter to only valid dict entries to match type contract- return {- pack_id: copy.deepcopy(meta)- for pack_id, meta in packs.items()- if isinstance(meta, dict)- }-- def keys(self) -> set:- """Get all preset IDs including corrupted entries.-- Lightweight method that returns IDs without deep-copying metadata.- Use this when you only need to check which presets are tracked.-- Returns:- Set of preset IDs (includes corrupted entries)- """- packs = self.data.get("presets", {}) or {}- if not isinstance(packs, dict):- return set()- return set(packs.keys())-- def list_by_priority(self, include_disabled: bool = False) -> List[tuple]:- """Get all installed presets sorted by priority.-- Lower priority number = higher precedence (checked first).- Presets with equal priority are sorted alphabetically by ID- for deterministic ordering.-- Args:- include_disabled: If True, include disabled presets. Default False.-- Returns:- List of (pack_id, metadata_copy) tuples sorted by priority.- Metadata is deep-copied to prevent accidental mutation.- """- packs = self.data.get("presets", {}) or {}- if not isinstance(packs, dict):- packs = {}- sortable_packs = []- for pack_id, meta in packs.items():- if not isinstance(meta, dict):- continue- # Skip disabled presets unless explicitly requested- if not include_disabled and not meta.get("enabled", True):- continue- metadata_copy = copy.deepcopy(meta)- metadata_copy["priority"] = normalize_priority(metadata_copy.get("priority", 10))- sortable_packs.append((pack_id, metadata_copy))- return sorted(- sortable_packs,- key=lambda item: (item[1]["priority"], item[0]),- )-- def is_installed(self, pack_id: str) -> bool:- """Check if preset is installed.-- Args:- pack_id: Preset ID-- Returns:- True if pack is installed, False if not or registry corrupted- """- packs = self.data.get("presets")- if not isinstance(packs, dict):- return False- return pack_id in packs---class PresetManager:- """Manages preset lifecycle: installation, removal, updates."""-- def __init__(self, project_root: Path):- """Initialize preset manager.-- Args:- project_root: Path to project root directory- """- self.project_root = project_root- self.presets_dir = project_root / ".specify" / "presets"- self.registry = PresetRegistry(self.presets_dir)-- def check_compatibility(- self,- manifest: PresetManifest,- speckit_version: str- ) -> bool:- """Check if preset is compatible with current spec-kit version.-- Args:- manifest: Preset manifest- speckit_version: Current spec-kit version-- Returns:- True if compatible-- Raises:- PresetCompatibilityError: If pack is incompatible- """- required = manifest.requires_speckit_version- # Defense in depth: the manifest validator now rejects a non-string- # requires.speckit_version, but this method is public and also reachable- # with a hand-built manifest object. ``InvalidSpecifier`` alone does not- # cover a non-string -- scalars raise TypeError from the constructor, and- # a list/dict is iterable so it constructs here and only breaks inside- # .contains(). Reject up front so this always reports a- # PresetCompatibilityError.- if not isinstance(required, str):- raise PresetCompatibilityError(- "Invalid version specifier: expected a string, got "- f"{type(required).__name__} ({required!r})"- )- try:- SpecifierSet(required) # Just to validate- except InvalidSpecifier:- raise PresetCompatibilityError(f"Invalid version specifier: {required}")-- if not version_satisfies(speckit_version, required):- raise PresetCompatibilityError(- f"Preset requires spec-kit {required}, "- f"but {speckit_version} is installed.\n"- f"Upgrade spec-kit with: {REINSTALL_COMMAND}"- )-- return True-- def find_unmet_extension_dependencies(- self,- manifest: PresetManifest- ) -> List[Dict[str, Any]]:- """Find declared extension dependencies that are not satisfied.-- Reports rather than raises. A preset whose overrides call into an- extension is written to degrade safely -- without the extension the- core workflow still runs -- so a missing dependency is a warning, not- an install failure. See issue #4231.-- Args:- manifest: Preset manifest to inspect-- Returns:- One entry per unsatisfied dependency, each with ``id``, the- requested ``version`` specifier (``None`` when unconstrained), the- ``installed`` version (``None`` when absent or unusable), and a- ``reason`` of ``"missing"``, ``"corrupt"``, ``"stale"``,- ``"disabled"``, or ``"version"``. Optional dependencies- (``required: false``) are never reported.-- An unreadable registry yields no results rather than raising, since- this runs after the install has already succeeded.-- A registry version that cannot be parsed is treated as- uncomparable, not as a mismatch: the extension is installed and- usable, and only its recorded version is unreadable. An extension- present on disk but absent from the registry is likewise treated as- satisfied, because resolution admits unregistered directories.- """- # Defense in depth, mirroring check_compatibility(): this method is- # public and also reachable with a hand-built manifest object that- # predates this field. A manifest without it declares nothing.- candidates = getattr(manifest, "requires_extensions", None)- if not isinstance(candidates, list):- return []-- # Collapse exact repeats so a manifest naming the same dependency twice- # warns once. Two entries for one id with *different* constraints are- # kept, since both genuinely have to hold.- declared: List[Dict[str, Any]] = []- seen: Set[tuple] = set()- for dep in candidates:- if not isinstance(dep, dict) or not dep.get("required", True):- continue- key = (dep.get("id"), dep.get("version"))- if key in seen:- continue- seen.add(key)- declared.append(dep)- if not declared:- return []-- extensions_dir = self.project_root / ".specify" / "extensions"- try:- registry = ExtensionRegistry(extensions_dir)- registered_ids = registry.keys()- registry_corrupt = registry.is_corrupt()- except OSError:- # Both reads can raise: _load() recovers from malformed content but- # deliberately lets OSError through, and is_corrupt() re-reads the- # file. This check runs *after* the install has completed, and- # preset_add only handles preset-domain errors, so letting that- # escape would turn a finished install into a traceback over a- # warning. An unreadable registry simply cannot be inspected.- return []-- unmet: List[Dict[str, Any]] = []-- for dep in declared:- metadata = registry.get(dep["id"])- if metadata is None:- # An absent registry entry does not mean the extension is- # unusable. _get_all_extensions_by_priority() admits a safe- # on-disk directory as an unregistered extension at implicit- # priority 10, so it resolves and the preset works -- but only- # when the registry is readable, since a corrupt one makes that- # path fail closed and contribute nothing.- #- # get() returns None for a corrupted (non-dict) entry as well as- # an absent one, but keys() retains corrupted ids -- both so- # resolution does not re-admit their directories as- # unregistered, and because is_installed() still counts them, so- # a plain `extension add` would be refused as already installed.- # That is a different state from absent, and needs a different- # remedy.- if dep["id"] in registered_ids:- unmet.append({**dep, "installed": None, "reason": "corrupt"})- continue- if (- (extensions_dir / dep["id"]).is_dir()- and PresetResolver._is_safe_registry_id(dep["id"])- and not registry_corrupt- ):- # Unregistered means no recorded version, so a constraint- # cannot be evaluated -- uncomparable, not unsatisfied.- continue- unmet.append({**dep, "installed": None, "reason": "missing"})- continue-- installed_version = metadata.get("version")- installed_version = (- installed_version if isinstance(installed_version, str) else None- )-- # A registry entry is not proof the extension can contribute. If- # its directory is gone, PresetResolver skips it outright (both- # template lookup and layer collection guard on ``is_dir()``), so- # the preset is as inert as if it were never installed -- but the- # surviving entry would otherwise read as satisfied.- if not (extensions_dir / dep["id"]).is_dir():- unmet.append(- {**dep, "installed": installed_version, "reason": "stale"}- )- continue-- # A disabled extension is registered but contributes nothing:- # resolution skips it (see _collect_extension_layers), so the- # preset is just as inert as if it were absent. Report it before- # any version check -- enabling it is the prerequisite, and the- # version may well be fine once it is.- if not metadata.get("enabled", True):- unmet.append(- {**dep, "installed": installed_version, "reason": "disabled"}- )- continue-- constraint = dep["version"]- if not constraint:- continue-- # A version that cannot be compared is not a mismatch. Absent or- # non-string is one way to be unusable; an unparseable string such- # as "unknown" is another, and version_satisfies() cannot tell them- # apart -- it catches InvalidVersion and returns False, which would- # report a mismatch against a version nobody can evaluate. Check- # parseability up front so only real comparisons reach the warning.- if installed_version is None or not _is_comparable_version(installed_version):- continue- if not version_satisfies(installed_version, constraint):- unmet.append(- {**dep, "installed": installed_version, "reason": "version"}- )-- return unmet-- def _register_commands(- self,- manifest: PresetManifest,- preset_dir: Path- ) -> Dict[str, List[str]]:- """Register preset command overrides with all detected AI agents.-- Scans the preset's templates for type "command", reads each command- file, and writes it to every detected agent directory using the- CommandRegistrar from the agents module.-- When a command uses a composition strategy (prepend, append, wrap),- the content is composed with the lower-priority command before- registration.-- Args:- manifest: Preset manifest- preset_dir: Installed preset directory-- Returns:- Dictionary mapping agent names to lists of registered command names- """- command_templates = [- t for t in manifest.templates if t.get("type") == "command"- ]- if not command_templates:- return {}-- # A preset command template always ships its own body, so it is- # self-contained and scaffolds regardless of whether any similarly- # named extension is installed. Namespaced names (speckit.<ns>.<cmd>)- # are treated exactly like short names (speckit.<cmd>) β they are NOT- # filtered out just because ``.specify/extensions/<ns>/`` is absent.- # The only command that cannot be materialized is a composition- # (prepend/append/wrap) with no base layer to compose onto; that case- # is handled per-command below (warn + skip), not by dropping names up- # front.- # Handle composition strategies: resolve composed content for non-replace commands- resolver = PresetResolver(self.project_root)- composed_dir = None- commands_to_register = []- for cmd in command_templates:- strategy = cmd.get("strategy", "replace")- if strategy != "replace":- # Only pre-compose if this preset is the top composing layer.- # If a higher-priority replace already wins, skip composition- # here β reconciliation will write the correct content.- layers = resolver.collect_all_layers(cmd["name"], "command")- top_layer_is_ours = (- layers and layers[0]["path"].is_relative_to(preset_dir)- )- if top_layer_is_ours:- composed = resolver.resolve_content(cmd["name"], "command")- if composed is not None:- if composed_dir is None:- composed_dir = preset_dir / ".composed"- composed_dir.mkdir(parents=True, exist_ok=True)- composed_file = composed_dir / f"{cmd['name']}.md"- composed_file.write_text(composed, encoding="utf-8")- commands_to_register.append({- **cmd,- "file": f".composed/{cmd['name']}.md",- })- else:- # No base layer to compose onto (e.g. the command it- # would wrap comes from an extension that isn't- # installed). Warn and skip this single command rather- # than aborting the whole install β mirrors the- # "composed is None" branch in- # _reconcile_composed_commands so command-mode and- # reconciliation behave identically.- import warnings- warnings.warn(- f"Command '{cmd['name']}' uses '{strategy}' "- f"strategy but no base command layer exists to "- f"compose onto; skipping. Provide a lower-priority "- f"preset, extension, or core command for it before "- f"using composition strategies.",- stacklevel=2,- )- continue- else:- # Not the top layer β register raw file; reconciliation- # will overwrite with the correct composed/winning content.- # Note: CommandRegistrar may process frontmatter strategy: wrap- # from the raw file (legacy compat), but reconciliation runs- # immediately after install and corrects the final output.- commands_to_register.append(cmd)- else:- commands_to_register.append(cmd)-- try:- from ..agents import CommandRegistrar- except ImportError:- return {}-- registrar = CommandRegistrar()-- # Single-active rule (#2948): preset command overrides register for- # the active integration only. A project without a recorded active- # integration (init-options.json does not exist at all β a legacy- # pre-init-options layout or direct library use) falls back to- # detection-based registration for all agents. A recorded key with- # no registrar config (e.g. "generic") naturally yields no matches- # via only_agent instead of falling back.- #- # An init-options.json that exists but is corrupted, unreadable, or- # has a malformed/empty "ai" value must not be treated the same as- # "no file" β that would silently reintroduce all-agent- # registration. Fail closed (register nothing) instead.- resolved_agent = resolve_active_agent_for_registration(self.project_root)- if resolved_agent is MISSING_INIT_OPTIONS_FILE:- active_agent = None- elif resolved_agent is None:- return {}- else:- active_agent = resolved_agent- # Mirror the extension path's ai_skills guard: when the active- # agent is a command-backed integration (extension != "/SKILL.md")- # running in skills mode, its preset command overrides render as- # skills via _register_skills, not as command files. Command-mode- # and skills-mode artifacts are mutually exclusive β writing both- # (e.g. `integration use copilot` with `--skills`) leaves a stale- # command file alongside the SKILL.md that is actually active.- init_options = load_init_options(self.project_root)- agent_config = registrar.AGENT_CONFIGS.get(active_agent)- if (- agent_config- and is_ai_skills_enabled(init_options)- and agent_config.get("extension") != "/SKILL.md"- ):- return {}-- return registrar.register_commands_for_all_agents(- commands_to_register,- manifest.id,- preset_dir,- self.project_root,- create_missing_active_skills_dir=True,- only_agent=active_agent,- )-- def register_enabled_presets_for_agent(self, agent_name: str) -> None:- """Re-register enabled presets' command overrides and skills for ``agent_name``.-- Mirrors ``ExtensionManager.register_enabled_extensions_for_agent`` for- presets (#2948): ``integration use`` / ``switch`` call this for the- newly active agent so a preset installed while a different- integration was active gets rescaffolded on activation, instead of- writing artifacts for inactive integrations at install time.- ``_register_commands`` / ``_register_skills`` already resolve the- active integration from init-options themselves, so this re-runs them- for every enabled preset and merges the fresh result for- ``agent_name`` into its stored registry metadata.-- Presets are processed in *reverse* priority order (lowest-precedence- first). Each pass overwrites the same target command/skill files, so- writing the highest-precedence preset last is what makes it win when- two enabled presets override the same command β matching the- priority stack documented for ``list_by_priority()``.- """- if not agent_name:- return-- # Resolve once: whether agent_name is a command-backed integration- # (extension != "/SKILL.md") currently running in skills mode, or- # vice versa. Native skill-only agents (extension == "/SKILL.md",- # e.g. claude/codex) have no command/skill toggle at all β both- # registered_commands and registered_skills legitimately co-exist- # for them by design, so this restriction only applies to- # command-backed integrations.- try:- from ..agents import CommandRegistrar-- agent_config = CommandRegistrar().AGENT_CONFIGS.get(agent_name)- except ImportError:- agent_config = None- is_command_backed = bool(agent_config) and agent_config.get("extension") != "/SKILL.md"- ai_skills_now = is_command_backed and is_ai_skills_enabled(- load_init_options(self.project_root)- )-- resolver = PresetResolver(self.project_root)- affected_cmd_names: set = set()- presets_by_priority = list(self.registry.list_by_priority())- winning_pack_by_command: Dict[str, str] = {}- winning_source_by_command: Dict[str, Path] = {}- project_override_commands: set[str] = set()- for candidate_pack_id, _candidate_metadata in presets_by_priority:- candidate_manifest = resolver._get_manifest(- self.presets_dir / candidate_pack_id- )- if candidate_manifest is None:- continue- for template in candidate_manifest.templates:- command_name = template.get("name")- if (- template.get("type") == "command"- and isinstance(command_name, str)- ):- if (- resolver.overrides_dir / f"{command_name}.md"- ).is_file():- project_override_commands.add(command_name)- winning_pack_by_command.setdefault(- command_name, candidate_pack_id- )- source_file = template.get("file")- if isinstance(source_file, str):- winning_source_by_command.setdefault(- command_name,- self.presets_dir- / candidate_pack_id- / source_file,- )-- pending_command_cleanups: List[- tuple[- str,- Dict[str, List[str]],- List[str],- Dict[str, str],- ]- ] = []- successful_skill_replacements: set[tuple[str, str]] = set()- pending_skill_cleanups: List[- tuple[- str,- Path,- Dict[str, List[str]],- List[str],- Dict[str, str],- ]- ] = []- successful_command_replacements: set[tuple[str, str]] = set()- for pack_id, metadata in reversed(presets_by_priority):- pack_dir = self.presets_dir / pack_id- manifest = resolver._get_manifest(pack_dir)- if manifest is None:- continue-- # Registration can write one command and then fail on a later- # template. Record names first so final reconciliation can repair- # any partial writes even when _register_commands never returns.- for tmpl in manifest.templates:- name = tmpl.get("name")- if tmpl.get("type") == "command" and isinstance(name, str):- affected_cmd_names.add(name)-- # Isolate per-preset failures: one preset that fails to register- # must not abort registration of the remaining enabled presets.- try:- registered_commands = self._register_commands(manifest, pack_dir)- registered_command_names = set(- registered_commands.get(agent_name) or []- )- for tmpl in manifest.templates:- if tmpl.get("type") != "command":- continue- primary_name = tmpl.get("name")- if (- isinstance(primary_name, str)- and primary_name in registered_command_names- ):- successful_command_replacements.add(- (pack_id, primary_name)- )- existing_commands = metadata.get("registered_commands", {})- if not isinstance(existing_commands, dict):- existing_commands = {}- merged_commands = copy.deepcopy(existing_commands)- # Toggled command -> skills for this same agent:- # _register_commands's ai_skills guard just made this a- # no-op, but the command file this preset wrote while- # command mode was active is still on disk and still- # tracked. Do NOT unregister it yet β _register_skills()- # below is an independently fallible replacement step, and- # deleting the old artifact before it succeeds would leave- # neither the old command file nor a new skill file if- # skills registration raises. The old artifact is only- # removed after the skills phase below completes without- # raising, preserving command/skill mutual exclusion while- # never leaving a transient failure with nothing in place- # (#2948).- stale_command_names: Optional[List[str]] = None- if registered_commands.get(agent_name):- existing_names = merged_commands.get(agent_name, [])- merged_commands[agent_name] = existing_names + [- name- for name in registered_commands[agent_name]- if name not in existing_names- ]- elif ai_skills_now and merged_commands.get(agent_name):- stale_command_names = merged_commands[agent_name]- # Persist the commands phase immediately, mirroring- # install_from_directory(): _register_skills is an- # independently fallible phase, and if it raises, the files- # the commands phase already wrote to disk must still be- # tracked so preset removal can clean them up (#2948).- if merged_commands != existing_commands:- self.registry.update(pack_id, {"registered_commands": merged_commands})-- registered_skills = self._register_skills(manifest, pack_dir)- replaced_skill_names = set(registered_skills.get(agent_name) or [])- for tmpl in manifest.templates:- if tmpl.get("type") != "command":- continue- primary_name = tmpl.get("name")- if not isinstance(primary_name, str):- continue- modern_name, legacy_name = self._skill_names_for_command(- primary_name- )- if (- modern_name in replaced_skill_names- or legacy_name in replaced_skill_names- ):- successful_skill_replacements.add(- (pack_id, primary_name)- )- raw_existing_skills = metadata.get("registered_skills")- if isinstance(raw_existing_skills, list) and raw_existing_skills:- # Legacy flat-list value: don't assume agent_name wrote- # every name (the first post-upgrade operation may be a- # direct switch to a different skill-mode agent) β- # infer real ownership from on-disk provenance instead- # (#2948).- existing_skills = self._infer_legacy_skill_provenance(- [n for n in raw_existing_skills if isinstance(n, str)],- pack_id,- fallback_agent=agent_name,- )- else:- existing_skills = self._normalize_registered_skills(- raw_existing_skills, fallback_agent=agent_name- )- merged_skills = copy.deepcopy(existing_skills)- if registered_skills.get(agent_name):- existing_names = merged_skills.get(agent_name, [])- merged_skills[agent_name] = existing_names + [- name- for name in registered_skills[agent_name]- if name not in existing_names- ]- elif is_command_backed and not ai_skills_now and merged_skills.get(agent_name):- # Mirror image: toggled skills -> command for this same- # agent. _get_skills_dir() no longer resolves a skills- # directory once ai_skills is off, so _register_skills- # is a no-op β but the SKILL.md this preset wrote while- # skills mode was active is still tracked and still on- # disk. Restore/remove it narrowly for this agent. This- # direction is already register-new-then-remove-old:- # _register_commands (the replacement) ran unconditionally- # above and only reaches here once it has already- # succeeded β but that call can still have returned- # empty or partial results (missing source template,- # safety-validation skip, corrupted manifest), so only- # retire the subset of stale skills whose corresponding- # command name was actually returned for this agent;- # anything unreplaced stays tracked and on disk (#2948).- stale_skill_names = merged_skills[agent_name]- skill_to_primary: Dict[str, str] = {}- for tmpl in manifest.templates:- if tmpl.get("type") != "command":- continue- primary_name = tmpl.get("name")- if not isinstance(primary_name, str):- continue- modern_name, legacy_name = self._skill_names_for_command(- primary_name- )- skill_to_primary[modern_name] = primary_name- skill_to_primary[legacy_name] = primary_name- pending_skill_cleanups.append(- (- pack_id,- pack_dir,- merged_skills,- stale_skill_names,- skill_to_primary,- )- )- # A legacy flat-list registered_skills value (predating- # per-agent provenance) must migrate to the dict format on- # disk even when the rescaffolded names are unchanged from- # what the list already held β comparing only the- # *normalized* forms would otherwise treat that as a no-op- # and leave the raw un-migrated list in the registry, which- # later removal/switch handling treats as legacy- # best-effort (restoring only the currently active agent's- # directory) instead of per-agent provenance (#2948).- needs_migration = (- isinstance(raw_existing_skills, list) and raw_existing_skills- )- if merged_skills != existing_skills or needs_migration:- self.registry.update(pack_id, {"registered_skills": merged_skills})-- # The skills phase above completed without raising, but a- # non-raising result can still be empty or partial (missing- # source template, safety-validation skip, corrupted- # manifest) β retiring every stale command purely on "did- # not raise" would delete a command whose replacement skill- # never actually landed, leaving neither artifact. Only- # retire the subset of stale commands whose corresponding- # skill name was actually returned for this agent; anything- # unreplaced stays tracked and on disk (#2948).- if stale_command_names:- # Commands may carry aliases (CommandRegistrar.register_- # commands() tracks and returns primary + alias names- # flattened together into one list), but _register_- # skills() only ever renders/returns the *primary*- # command name's skill β running an alias's own name- # through _skill_names_for_command() never matches- # anything real, so an alias would stay tracked/on-disk- # forever even after its primary's skill replacement- # landed. Map each stale name back to its template's- # primary via the manifest so the whole primary+alias- # group is retired or kept together, based solely on- # whether the *primary*'s skill replacement actually- # landed (#2948).- alias_to_primary: Dict[str, str] = {}- for tmpl in manifest.templates:- if tmpl.get("type") != "command":- continue- primary_name = tmpl.get("name")- if not isinstance(primary_name, str):- continue- for alias in tmpl.get("aliases", []):- if isinstance(alias, str):- alias_to_primary[alias] = primary_name-- pending_command_cleanups.append(- (- pack_id,- merged_commands,- stale_command_names,- alias_to_primary,- )- )- except Exception as pack_err:- from .. import _print_cli_warning-- _print_cli_warning(- "register preset artifacts for",- "preset",- pack_id,- pack_err,- continuing="Continuing with the remaining presets.",- )- continue-- # Registration writes each preset's raw layer. Reconcile before- # retiring opposite-mode artifacts so project overrides and composed- # winners are materialized first, and so cleanup runs last instead of- # being undone by skill reconciliation.- reconciled_commands: set[str] = set()- reconciled_skills: set[str] = set()- if affected_cmd_names:- try:- reconciled_commands = self._reconcile_composed_commands(- list(affected_cmd_names), target_agent=agent_name- )- reconciled_skills = self._reconcile_skills(- list(affected_cmd_names), target_agent=agent_name- )- except Exception as exc:- import warnings-- warnings.warn(- f"Post-rescaffold reconciliation failed for '{agent_name}': "- f"{exc}. Agent command files may be stale; re-run "- f"'specify integration use {agent_name}' or reinstall "- f"affected presets to refresh.",- stacklevel=2,- )-- successfully_replaced_winners = {- command_name- for command_name, winning_pack_id in winning_pack_by_command.items()- if command_name not in project_override_commands- and (- (winning_pack_id, command_name)- in successful_skill_replacements- or (- command_name in reconciled_skills- and command_name in winning_source_by_command- and winning_source_by_command[command_name].is_file()- )- )- }- successfully_replaced_winners.update(- project_override_commands & reconciled_skills- )-- for (- pack_id,- merged_commands,- stale_command_names,- alias_to_primary,- ) in pending_command_cleanups:- fully_replaced = [- command_name- for command_name in stale_command_names- if alias_to_primary.get(command_name, command_name)- in successfully_replaced_winners- ]- if not fully_replaced:- continue- remaining_stale = [- command_name- for command_name in stale_command_names- if command_name not in fully_replaced- ]- self._unregister_commands({agent_name: fully_replaced})- if remaining_stale:- merged_commands[agent_name] = remaining_stale- else:- merged_commands.pop(agent_name, None)- self.registry.update(- pack_id, {"registered_commands": merged_commands}- )-- successfully_replaced_command_winners = {- command_name- for command_name, winning_pack_id in winning_pack_by_command.items()- if command_name not in project_override_commands- and (- (winning_pack_id, command_name)- in successful_command_replacements- or (- command_name in reconciled_commands- and command_name in winning_source_by_command- and winning_source_by_command[command_name].is_file()- )- )- }- successfully_replaced_command_winners.update(- project_override_commands & reconciled_commands- )-- # Skill restoration walks the priority stack, so retire stale layers- # from highest to lowest. The last cleanup then restores the true- # non-preset fallback (or removes the skill) rather than cycling back- # to a lower-priority preset.- for (- pack_id,- pack_dir,- merged_skills,- stale_skill_names,- skill_to_primary,- ) in reversed(pending_skill_cleanups):- fully_replaced = [- skill_name- for skill_name in stale_skill_names- if skill_to_primary.get(skill_name)- in successfully_replaced_command_winners- ]- if not fully_replaced:- continue- remaining_stale = [- skill_name- for skill_name in stale_skill_names- if skill_name not in fully_replaced- ]- override_sources = {- skill_name: f"override:{skill_to_primary[skill_name]}"- for skill_name in fully_replaced- if skill_name in skill_to_primary- }- self._unregister_skills(- {agent_name: fully_replaced},- pack_dir,- additional_owned_sources=override_sources,- )- if remaining_stale:- merged_skills[agent_name] = remaining_stale- else:- merged_skills.pop(agent_name, None)- self.registry.update(- pack_id, {"registered_skills": merged_skills}- )-- def unregister_agent_artifacts(self, agent_name: str) -> None:- """Remove ``agent_name``'s tracked preset command/skill artifacts.-- Mirrors ``ExtensionManager.unregister_agent_artifacts()`` (#2948):- used by ``integration switch`` when deactivating the previous- integration, so a preset's command overrides and skill mirrors- written for that agent don't linger as orphans in its directory- once a different (possibly not-yet-installed) integration becomes- active β including custom preset commands and files the registrar- would otherwise skip as user-modified.-- Scoped strictly to ``agent_name``: only that agent's own tracked- artifacts and registry entries are touched. Other agents' files,- tracking, and preset packs themselves are left untouched, and no- priority-stack reconciliation runs β this is agent-scoped cleanup- only, not preset removal.- """- if not agent_name:- return-- try:- from ..agents import CommandRegistrar-- registrar = CommandRegistrar()- agent_config = registrar.AGENT_CONFIGS.get(agent_name)- except ImportError:- registrar = None- agent_config = None- if agent_config is None or registrar is None:- return-- for pack_id, metadata in list(self.registry.list().items()):- updates: Dict[str, Any] = {}-- raw_skills = metadata.get("registered_skills", [])- if isinstance(raw_skills, list) and raw_skills:- # Legacy flat-list value predating per-agent provenance:- # infer real ownership from on-disk markers before removing- # anything, so only agent_name's actual share is unregistered- # and the rest migrates to per-agent form instead of either- # guessing every name belongs to agent_name or blindly- # leaving other agents' shares unrecoverable (#2948).- registered_skills_all = self._infer_legacy_skill_provenance(- [n for n in raw_skills if isinstance(n, str)],- pack_id,- fallback_agent=agent_name,- )- skills_migrated = True- elif isinstance(raw_skills, dict):- registered_skills_all = copy.deepcopy(raw_skills)- skills_migrated = False- else:- registered_skills_all = {}- skills_migrated = False-- registered_commands = metadata.get("registered_commands", {})- if not isinstance(registered_commands, dict):- registered_commands = {}-- agent_command_names = [- n for n in registered_commands.get(agent_name, []) if isinstance(n, str)- ]-- # Native SKILL.md agents (claude/codex/agy/β¦) materialize their- # preset override in _register_commands(), tracked under- # registered_commands, not registered_skills β see- # _register_skills()'s own docstring ("Native skill agents β¦- # materialize brand-new preset skills in _register_commands()").- # A legacy flat-list registered_skills value predating that- # split can still attribute the very same on-disk file to this- # agent via provenance inference; unregistering through both- # paths would double-process the identical directory (delete- # via the commands path, then no-op "restore" via the skills- # path since the directory is already gone). Mirror remove()'s- # own coordination: whenever this agent's artifact is already- # handled via registered_commands, never additionally treat it- # as a registered_skills entry for the same agent.- native_skills_entry_removed = False- if agent_command_names and agent_config.get("extension") == "/SKILL.md":- native_skills_entry_removed = agent_name in registered_skills_all- registered_skills_all.pop(agent_name, None)-- if agent_command_names:- command_names_to_unregister = agent_command_names- if agent_config.get("extension") == "/SKILL.md":- agent_output = registrar._resolve_agent_dir(- agent_name, agent_config, self.project_root- )- shared_names: set[str] = set()- for other_agent, other_names in registered_commands.items():- if (- other_agent == agent_name- or not isinstance(other_names, list)- ):- continue- other_config = registrar.AGENT_CONFIGS.get(other_agent)- if (- not other_config- or other_config.get("extension") != "/SKILL.md"- ):- continue- other_output = registrar._resolve_agent_dir(- other_agent, other_config, self.project_root- )- if other_output == agent_output:- shared_names.update(- name- for name in other_names- if isinstance(name, str)- )- command_names_to_unregister = [- name- for name in agent_command_names- if name not in shared_names- ]- if command_names_to_unregister:- self._unregister_commands(- {agent_name: command_names_to_unregister}- )- new_registered_commands = copy.deepcopy(registered_commands)- new_registered_commands.pop(agent_name, None)- updates["registered_commands"] = new_registered_commands-- agent_skill_names = registered_skills_all.get(agent_name) or []- if (- agent_skill_names- or skills_migrated- or native_skills_entry_removed- ):- if agent_skill_names:- self._delete_agent_preset_skills(- agent_name, agent_skill_names, pack_id- )- remaining = {- other_agent: names- for other_agent, names in registered_skills_all.items()- if other_agent != agent_name- }- updates["registered_skills"] = remaining-- if updates:- self.registry.update(pack_id, updates)-- def _unregister_commands(self, registered_commands: Dict[str, List[str]]) -> None:- """Remove previously registered command files from agent directories.-- Args:- registered_commands: Dict mapping agent names to command name lists- """- try:- from ..agents import CommandRegistrar- except ImportError:- return-- registrar = CommandRegistrar()- registrar.unregister_commands(registered_commands, self.project_root)-- def _merge_pack_registered_commands(- self, pack_id: str, written: Optional[Dict[str, List[str]]]- ) -> None:- """Merge actually-written agent command registrations into a preset's metadata.-- Reconciliation (``_reconcile_composed_commands``) can write a- preset's content into an agent directory the preset never wrote to- before β most notably a historical (currently inactive) agent- supplied via ``extra_agents`` when a higher-priority preset is- removed. If that write isn't reflected back into the winning- preset's own ``registered_commands``, the registry silently lies- about which directories the preset owns: a later removal of this- same preset only cleans up the agents it already knew about,- orphaning the directory reconciliation just wrote to on its behalf- (#2948).-- Args:- pack_id: The preset whose metadata should be updated.- written: ``{agent_name: [cmd_name, ...]}`` actually written by- the reconciliation call just made, exactly mirroring- ``CommandRegistrar.register_commands_for_non_skill_agents``'s- return value. A falsy value is a no-op.- """- if not written:- return- metadata = self.registry.get(pack_id)- if metadata is None:- return # pack_id no longer installed (e.g. removed mid-loop)- existing_commands = metadata.get("registered_commands", {})- if not isinstance(existing_commands, dict):- existing_commands = {}- merged_commands = copy.deepcopy(existing_commands)- changed = False- for agent_name, cmd_names in written.items():- if not cmd_names:- continue- existing_names = merged_commands.get(agent_name, [])- new_names = [n for n in cmd_names if n not in existing_names]- if new_names:- merged_commands[agent_name] = existing_names + new_names- changed = True- if changed:- self.registry.update(pack_id, {"registered_commands": merged_commands})-- def _merge_extension_registered_commands(- self, extension_id: str, written: Optional[Dict[str, List[str]]]- ) -> None:- """Merge reconciliation writes into an extension's registry entry."""- if not written:- return- registry = ExtensionRegistry(self.project_root / ".specify" / "extensions")- metadata = registry.get(extension_id)- if metadata is None:- return- existing_commands = metadata.get("registered_commands", {})- if not isinstance(existing_commands, dict):- existing_commands = {}- merged_commands = copy.deepcopy(existing_commands)- changed = False- for agent_name, cmd_names in written.items():- existing_names = merged_commands.get(agent_name, [])- new_names = [name for name in cmd_names if name not in existing_names]- if new_names:- merged_commands[agent_name] = existing_names + new_names- changed = True- if changed:- registry.update(extension_id, {"registered_commands": merged_commands})-- def _reconcile_composed_commands(- self,- command_names: List[str],- extra_agents: Optional[Set[str]] = None,- target_agent: Optional[str] = None,- ) -> Set[str]:- """Re-resolve and re-register composed commands from the full stack.-- After install or remove, recompute the effective content for each- command name that participates in composition, and write the winning- content to the agent directories. This ensures command files always- reflect the current priority stack rather than depending on- install/remove order.-- Single-active rule (#2948): non-skill command-file registration- performed by this pass is restricted to the active integration, the- same as ``_register_commands``. Without this, reconciliation after- install/remove would write command files for every detected- non-skill agent even though registration itself is active-only,- leaving inactive integrations with artifacts that are never- recorded in ``registered_commands`` (and therefore never cleaned up- on removal).-- Args:- command_names: List of command names to reconcile- extra_agents: Additional agent names to also reconcile besides- the currently active one. Populated by ``remove()`` with the- historical agents a just-removed preset's- ``registered_commands`` actually targeted, so a surviving- lower-priority preset's content is restored there too β not- only for the currently active agent (#2948). Install/use- callers omit this, preserving pure active-only behavior.- target_agent: If set, report only command names written for this- agent. Other callers receive the union of all written names.-- Returns:- Command names successfully written by this reconciliation pass.- """- if not command_names:- return set()-- # Every preset-owned command name flows through unchanged. Names are- # NOT filtered by the ``speckit.<ns>.<cmd>`` shape: a self-contained- # preset command scaffolds whether or not a like-named extension is- # installed (parity with _register_commands), and a name whose base- # layer has disappeared must still reach the loop below so its now- # uncomposable stale file gets unregistered. The loop already skips- # names that resolve to no layers at all (``if not layers: continue``).- try:- from ..agents import CommandRegistrar- except ImportError:- return set()-- resolver = PresetResolver(self.project_root)- registrar = CommandRegistrar()- reconciled_commands: set[str] = set()-- def record_written(written: Dict[str, List[str]]) -> None:- if target_agent is not None:- reconciled_commands.update(written.get(target_agent, []))- else:- for names in written.values():- reconciled_commands.update(names)-- # Resolve the active-only restriction once. MISSING_INIT_OPTIONS_FILE- # (legacy pre-init-options project) keeps the pre-#2948 fallback of- # registering every detected non-skill agent; a corrupted/malformed- # init-options.json fails closed via a sentinel that matches no real- # agent name instead of silently falling back to "no restriction".- resolved_agent = resolve_active_agent_for_registration(self.project_root)- if resolved_agent is MISSING_INIT_OPTIONS_FILE:- only_agent: Optional[str] = None- elif resolved_agent is None:- only_agent = ""- else:- only_agent = resolved_agent- # Mirror _register_commands's ai_skills guard: a command-backed- # active agent running in skills mode renders preset/extension- # overrides as skills, not command files, so this non-skill- # command reconciliation pass must not target it either.- agent_config = registrar.AGENT_CONFIGS.get(only_agent)- if (- agent_config- and is_ai_skills_enabled(load_init_options(self.project_root))- and agent_config.get("extension") != "/SKILL.md"- ):- only_agent = ""-- # The active agent's participation is decided exclusively by the- # only_agent guard above (which encodes the ai_skills mode). A- # partially failed commandβskills toggle can leave the active agent- # behind in extra_agents via its stale registered_commands entry,- # and register_commands_for_non_skill_agents admits every- # extra_agents member even when only_agent excludes the agent β- # recreating a command file for an agent now running in skills- # mode. Never re-admit the active agent through the- # historical-agents side channel (#2948).- if extra_agents and isinstance(resolved_agent, str):- extra_agents = set(extra_agents) - {resolved_agent}-- # Cache registry and manifests outside the loop to avoid- # repeated filesystem reads for each command name.- presets_by_priority = list(self.registry.list_by_priority())-- for cmd_name in command_names:- layers = resolver.collect_all_layers(cmd_name, "command")- if not layers:- continue-- # If the top layer is replace, it wins entirely β lower layers- # are irrelevant regardless of their strategies.- top_is_replace = layers[0]["strategy"] == "replace"- has_composition = not top_is_replace and any(- layer["strategy"] != "replace" for layer in layers- )- if not has_composition:- # Pure replace β the top layer wins.- top_layer = layers[0]- top_path = top_layer["path"]- # Try to find which preset owns this layer- registered = False- for pack_id, _meta in presets_by_priority:- pack_dir = self.presets_dir / pack_id- if top_path.is_relative_to(pack_dir):- manifest = resolver._get_manifest(pack_dir)- if manifest:- for tmpl in manifest.templates:- if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":- written = self._register_for_non_skill_agents(- registrar, [tmpl], manifest.id, pack_dir,- only_agent=only_agent, extra_agents=extra_agents,- )- record_written(written)- self._merge_pack_registered_commands(manifest.id, written)- registered = True- break- break- if not registered:- # Top layer is a non-preset source (extension, core, or- # project override). Register directly from the layer path.- source = layers[0]["source"]- extension_id = None- written: Dict[str, List[str]] = {}- if source.startswith("extension:"):- # Use extension's own registration to preserve context formatting- extension_id = source.split(":", 1)[1].split(" ", 1)[0]- ext_dir = (- self.project_root / ".specify" / "extensions" / extension_id- )- ext_manifest_path = ext_dir / "extension.yml"- if ext_manifest_path.exists():- try:- from ..extensions import ExtensionManifest- ext_manifest = ExtensionManifest(ext_manifest_path)- # Filter to only the command being reconciled- matching_cmds = [- c for c in ext_manifest.commands- if c.get("name") == cmd_name- ]- if matching_cmds:- written = registrar.register_commands_for_non_skill_agents(- matching_cmds, extension_id, ext_dir,- self.project_root,- context_note=f"\n<!-- Extension: {extension_id} -->\n<!-- Config: .specify/extensions/{extension_id}/ -->\n",- extension_id=extension_id,- only_agent=only_agent,- extra_agents=extra_agents,- )- record_written(written)- registered = True- except (ImportError, FileNotFoundError, OSError):- # Extension registration failed; fall back to- # generic path-based registration below.- pass- if not registered:- source_id = extension_id or source- written = self._register_command_from_path(- registrar, cmd_name, top_path,- source_id=source_id,- only_agent=only_agent, extra_agents=extra_agents,- )- record_written(written)- if extension_id:- self._merge_extension_registered_commands(- extension_id, written- )- else:- # Composed command β resolve from full stack- composed = resolver.resolve_content(cmd_name, "command")- if composed is None:- # Composition no longer possible (e.g. base layer removed).- # Unregister any stale command file from non-skill agents.- import warnings- warnings.warn(- f"Cannot compose command '{cmd_name}': no base layer. "- f"Stale command files may remain.",- stacklevel=2,- )- registrar._ensure_configs()- # Include aliases from the top layer's manifest- cmd_names_to_unregister = [cmd_name]- for _pid, _meta in presets_by_priority:- _pd = self.presets_dir / _pid- _m = resolver._get_manifest(_pd)- if _m:- for _t in _m.templates:- if _t.get("name") == cmd_name and _t.get("type") == "command":- for alias in _t.get("aliases", []):- if isinstance(alias, str):- cmd_names_to_unregister.append(alias)- break- # Mirror the active-only restriction used elsewhere in- # this pass: without it, unregistering a stale composed- # command would touch every non-skill agent's directory,- # deleting historical artifacts from integrations that- # were never active when this preset registered (#2948).- registrar.unregister_commands(- {- agent: cmd_names_to_unregister- for agent in registrar.AGENT_CONFIGS- if registrar.AGENT_CONFIGS[agent].get("extension") != "/SKILL.md"- and (- only_agent is None- or agent == only_agent- or agent in (extra_agents or ())- )- },- self.project_root,- )- continue-- # Write to the highest-priority preset's .composed dir- registered = False- for pack_id, _meta in presets_by_priority:- pack_dir = self.presets_dir / pack_id- manifest = resolver._get_manifest(pack_dir)- if not manifest:- continue- for tmpl in manifest.templates:- if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":- composed_dir = pack_dir / ".composed"- composed_dir.mkdir(parents=True, exist_ok=True)- composed_file = composed_dir / f"{cmd_name}.md"- composed_file.write_text(composed, encoding="utf-8")- written = self._register_for_non_skill_agents(- registrar,- [{**tmpl, "file": f".composed/{cmd_name}.md"}],- manifest.id, pack_dir,- only_agent=only_agent, extra_agents=extra_agents,- )- record_written(written)- self._merge_pack_registered_commands(manifest.id, written)- registered = True- break- else:- continue- break- if not registered:- # No preset owns this composed command β write to a- # shared .composed dir and register from the top layer.- shared_composed = self.presets_dir / ".composed"- shared_composed.mkdir(parents=True, exist_ok=True)- composed_file = shared_composed / f"{cmd_name}.md"- composed_file.write_text(composed, encoding="utf-8")- source = layers[0]["source"]- if source.startswith("extension:"):- source_id = source.split(":", 1)[1].split(" ", 1)[0]- else:- source_id = source- written = self._register_command_from_path(- registrar, cmd_name, composed_file,- source_id=source_id,- only_agent=only_agent, extra_agents=extra_agents,- )- record_written(written)- if source.startswith("extension:"):- self._merge_extension_registered_commands(- source_id, written- )-- return reconciled_commands-- def _register_command_from_path(- self,- registrar: Any,- cmd_name: str,- cmd_path: Path,- source_id: str = "reconciled",- only_agent: Optional[str] = None,- extra_agents: Optional[Set[str]] = None,- ) -> Dict[str, List[str]]:- """Register a single command from a file path (non-preset source).-- Used by reconciliation when the winning layer is an extension,- core template, or project override rather than a preset.-- Args:- registrar: CommandRegistrar instance- cmd_name: Command name- cmd_path: Path to the command file- source_id: Source attribution for rendered output- only_agent: If set, restrict registration to this single agent (#2948).- extra_agents: Additional agent names to register for besides- ``only_agent`` (post-removal reconciliation only, #2948).-- Returns:- ``{agent_name: [cmd_name, ...]}`` for every agent this call- actually registered the command for (empty if the source path- doesn't exist or nothing was written).- """- if not cmd_path.exists():- return {}- cmd_tmpl: Dict[str, Any] = {- "name": cmd_name,- "type": "command",- "file": cmd_path.name,- }- # Load aliases from extension manifest when the winning layer is an extension- if source_id and not source_id.startswith("preset:"):- try:- from ..extensions import ExtensionManifest- for ext_dir in (self.project_root / ".specify" / "extensions").iterdir():- if not ext_dir.is_dir():- continue- if cmd_path.is_relative_to(ext_dir):- manifest_path = ext_dir / "extension.yml"- if manifest_path.exists():- ext_manifest = ExtensionManifest(manifest_path)- for cmd in ext_manifest.commands:- if cmd.get("name") == cmd_name:- aliases = cmd.get("aliases", [])- if isinstance(aliases, list) and aliases:- cmd_tmpl["aliases"] = aliases- break- break- except Exception:- pass # best-effort alias loading- return self._register_for_non_skill_agents(- registrar, [cmd_tmpl], source_id, cmd_path.parent,- only_agent=only_agent, extra_agents=extra_agents,- )-- def _register_for_non_skill_agents(- self,- registrar: Any,- commands: List[Dict[str, Any]],- source_id: str,- source_dir: Path,- only_agent: Optional[str] = None,- extra_agents: Optional[Set[str]] = None,- ) -> Dict[str, List[str]]:- """Register commands for non-skill agents during reconciliation.-- Skill-based agents (``/SKILL.md`` layout) are handled separately:- - On removal: ``_unregister_skills()`` restores from core/extension,- then ``_reconcile_skills()`` re-runs ``_register_skills()`` for the- next winning preset so SKILL.md files get proper frontmatter and- descriptions.- - On install: ``_register_skills()`` writes formatted SKILL.md, then- ``_reconcile_skills()`` ensures the actual priority winner is used.-- Writing raw command content to skill agents would produce invalid- SKILL.md files (missing skill frontmatter, descriptions, etc.).-- Args:- only_agent: If set, restrict registration to this single agent,- matching the active-only rule applied by ``_register_commands``- (#2948).- extra_agents: Additional agent names to register for besides- ``only_agent``. Used by post-removal reconciliation to also- restore surviving content into historical agent directories- a just-removed preset actually wrote to (#2948).-- Returns:- ``{agent_name: [cmd_name, ...]}`` for every agent this call- actually registered a command for, mirroring- ``CommandRegistrar.register_commands_for_non_skill_agents``'s- return value so callers can merge it into a preset's own- ``registered_commands`` tracking (#2948).- """- return registrar.register_commands_for_non_skill_agents(- commands, source_id, source_dir, self.project_root,- only_agent=only_agent, extra_agents=extra_agents,- )-- class _FilteredManifest:- """Wrapper that exposes only selected command templates from a manifest.-- Used by _reconcile_skills to avoid overwriting skills for commands- that aren't being reconciled.- """-- def __init__(self, manifest: "PresetManifest", cmd_names: set):- self._manifest = manifest- self._cmd_names = cmd_names-- def __getattr__(self, name: str):- return getattr(self._manifest, name)-- @property- def templates(self) -> List[Dict[str, Any]]:- return [- t for t in self._manifest.templates- if t.get("name") in self._cmd_names- ]-- def _merge_pack_registered_skills(- self, pack_id: str, written: Optional[Dict[str, List[str]]]- ) -> None:- """Merge actually-written agent skill registrations into a preset's metadata.-- Mirrors :meth:`_merge_pack_registered_commands` for the skills- side: ``_reconcile_skills`` can render a preset's SKILL.md content- into an agent directory the preset never wrote to before β most- notably a historical (currently inactive) agent restored via- ``extra_skills_dirs`` when a higher-priority preset is removed. If- that write isn't reflected back into the winning preset's own- ``registered_skills``, a later removal of this same preset only- cleans up the agents it already knew about, orphaning the skill- directory reconciliation just wrote to on its behalf (#2948).-- Args:- pack_id: The preset whose metadata should be updated.- written: ``{agent_name: [skill_name, ...]}`` actually written- by the ``_register_skills`` call just made. A falsy value- is a no-op.- """- if not written:- return- metadata = self.registry.get(pack_id)- if metadata is None:- return # pack_id no longer installed (e.g. removed mid-loop)- raw_existing_skills = metadata.get("registered_skills")- if isinstance(raw_existing_skills, list) and raw_existing_skills:- # Legacy flat-list value: infer real per-agent ownership from- # on-disk provenance rather than guessing (#2948).- fallback_agent = next(iter(written)) if written else None- existing_skills = self._infer_legacy_skill_provenance(- [n for n in raw_existing_skills if isinstance(n, str)],- pack_id,- fallback_agent=fallback_agent,- )- else:- existing_skills = self._normalize_registered_skills(raw_existing_skills)- merged_skills = copy.deepcopy(existing_skills)- changed = (- isinstance(raw_existing_skills, list) and bool(raw_existing_skills)- )- for agent_name, skill_names in written.items():- if not skill_names:- continue- existing_names = merged_skills.get(agent_name, [])- new_names = [n for n in skill_names if n not in existing_names]- if new_names:- merged_skills[agent_name] = existing_names + new_names- changed = True- if changed:- self.registry.update(pack_id, {"registered_skills": merged_skills})-- def _reconcile_skills(- self,- command_names: List[str],- extra_skills_dirs: Optional[- Dict[Path, tuple[Optional[str], List[str]]]- ] = None,- target_agent: Optional[str] = None,- ) -> Set[str]:- """Re-register skills for commands whose winning layer changed.-- After a preset is removed, finds the next preset in the priority- stack that provides each command and re-runs skill registration- for that preset so SKILL.md files reflect the current winner.-- Args:- command_names: List of command names to reconcile skills for- extra_skills_dirs: Additional- ``{skills_dir: (renderer_agent, managed_skill_names)}``- entries restored by ``_unregister_skills``. Reconciliation- is limited to the names actually managed in each directory.- target_agent: If set, report only command names written for this- agent. Other callers receive the union of all written names.-- Returns:- Command names whose skill output was successfully written.- """- if not command_names:- return set()-- # Preset-owned command names are not filtered by the- # ``speckit.<ns>.<cmd>`` shape here either: a self-contained preset- # command renders its skill whether or not a like-named extension is- # installed. The per-name loop below skips anything that doesn't- # resolve to a managed skill directory.- resolver = PresetResolver(self.project_root)- active_skills_dir = self._get_skills_dir()-- from .. import load_init_options-- init_opts = load_init_options(self.project_root)- active_ai = init_opts.get("ai") if isinstance(init_opts, dict) else None- if not isinstance(active_ai, str) or not active_ai:- active_ai = None-- # Cache registry once to avoid repeated filesystem reads- presets_by_priority = list(self.registry.list_by_priority())-- # Group command names by winning preset to batch _register_skills calls- # while only registering skills for the specific commands being- # reconciled. This resolution (which preset/content wins) is- # directory-independent, so it's computed once and then applied to- # every affected directory below.- preset_cmds: Dict[str, List[str]] = {}- non_preset_skills: List[tuple] = []- managed_skill_names: set = set()- reconciled_skill_commands: set[str] = set()-- for cmd_name in command_names:- layers = resolver.collect_all_layers(cmd_name, "command")- if not layers:- continue-- skill_name, legacy_skill_name = self._skill_names_for_command(- cmd_name- )- candidate_skill_names = {skill_name, legacy_skill_name}- # Track whether any preset previously registered this skill- # (i.e., it was actively managed), so a not-yet-existing skill- # dir can be re-created per affected directory below.- for _pid, meta in presets_by_priority:- if not isinstance(meta, dict):- continue- recorded = meta.get("registered_skills", [])- if isinstance(recorded, dict):- recorded_names = {- name- for names in recorded.values()- if isinstance(names, list)- for name in names- }- elif isinstance(recorded, list):- recorded_names = set(recorded)- else:- recorded_names = set()- recorded_candidates = (- candidate_skill_names & recorded_names- )- if recorded_candidates:- managed_skill_names.update(recorded_candidates)-- top_path = layers[0]["path"]- # Find the preset that owns the winning layer- found_preset = False- for pack_id, _meta in presets_by_priority:- pack_dir = self.presets_dir / pack_id- if top_path.is_relative_to(pack_dir):- preset_cmds.setdefault(pack_id, []).append(cmd_name)- found_preset = True- break- if not found_preset:- # Winner is a non-preset source (core/extension/override).- # Track the winning layer path for skill restoration.- non_preset_skills.append((skill_name, cmd_name, layers[0]))-- core_ext_skills = [s for s in non_preset_skills if s[2]["source"] != "project override"]- override_skills = [s for s in non_preset_skills if s[2]["source"] == "project override"]-- def apply_to_dir(- skills_dir: Path,- dir_agent: Optional[str],- *,- is_active: bool,- managed_names: Optional[Set[str]] = None,- ) -> None:- dir_managed_names = (- managed_skill_names if managed_names is None else managed_names- )- # Restore skills for commands whose winner is non-preset.- # _unregister_skills_in_dir can rmtree the skill dir, so- # overrides must be handled directly (create dir + write)- # without that call.- dir_core_ext_names = [- candidate- for _skill_name, cmd_name, _top_layer in core_ext_skills- for candidate in self._skill_names_for_command(cmd_name)- if candidate in dir_managed_names- ]- if dir_core_ext_names:- self._unregister_skills_in_dir(- dir_core_ext_names,- skills_dir,- dir_agent,- restore_from_bundled_core=True,- )-- for _skill_name, cmd_name, top_layer in override_skills:- target_skill_names = [- name- for name in self._skill_names_for_command(cmd_name)- if name in dir_managed_names- ]- if not target_skill_names:- continue- try:- from ..agents import CommandRegistrar- from .. import SKILL_DESCRIPTIONS- from ..shared_infra import _write_shared_text- registrar = CommandRegistrar()- content = top_layer["path"].read_text(encoding="utf-8")- fm, body = registrar.parse_frontmatter(content)- short_name = cmd_name- if short_name.startswith("speckit."):- short_name = short_name[len("speckit."):]- desc = fm.get("description", "") or SKILL_DESCRIPTIONS.get(- short_name.replace(".", "-"),- f"Command: {short_name}",- )- selected_ai = dir_agent if isinstance(dir_agent, str) else ""- if selected_ai:- body = registrar.resolve_skill_placeholders(- selected_ai, fm, body, self.project_root- )- body = self._resolve_skill_command_refs(- body, registrar, selected_ai, self.project_root- )- from ..integrations import get_integration- integration = get_integration(selected_ai) if selected_ai else None- skill_title = self._skill_title_from_command(cmd_name)- wrote_override = False- for target_skill_name in target_skill_names:- skill_subdir = skills_dir / target_skill_name- # Same symlink guard as _register_skills's- # registration path (#2948).- if not self._validate_skill_subdir(- skill_subdir,- create=True,- skills_root=skills_dir,- ):- continue- fm_data = registrar.build_skill_frontmatter(- selected_ai,- target_skill_name,- desc,- f"override:{cmd_name}",- )- registrar.apply_argument_hint(- fm, fm_data, integration- )- fm_text = dump_frontmatter(fm_data)- skill_content = (- f"---\n{fm_text}\n---\n\n"- f"# Speckit {skill_title} Skill\n\n{body}\n"- )- if integration is not None and hasattr(- integration, "post_process_skill_content"- ):- skill_content = (- integration.post_process_skill_content(- skill_content- )- )- _write_shared_text(- skills_dir,- skill_subdir / "SKILL.md",- skill_content,- )- wrote_override = True- if (- wrote_override- and (- target_agent is None- or dir_agent == target_agent- )- ):- reconciled_skill_commands.add(cmd_name)- except Exception:- pass # best-effort override skill restoration-- # Register skills only for the specific commands being- # reconciled, not all commands in each winning preset's- # manifest.- for pack_id, cmds in preset_cmds.items():- dir_cmds = [- cmd- for cmd in cmds- if any(- name in dir_managed_names- for name in self._skill_names_for_command(cmd)- )- ]- if not dir_cmds:- continue- pack_dir = self.presets_dir / pack_id- manifest_path = pack_dir / "preset.yml"- if not manifest_path.exists():- continue- try:- manifest = PresetManifest(manifest_path)- except PresetValidationError:- continue- cmds_set = set(dir_cmds)- filtered_manifest = self._FilteredManifest(manifest, cmds_set)- # Not dead code: _register_skills only *overwrites* skill- # subdirectories that already exist (plus brand-new ones for- # the active ai_skills agent). For a restore into a- # historical directory, _unregister_skills has just deleted- # the retiring preset's subdirectory, so pre-create the- # tracked (dir_managed_names) subdirectories here β under- # the same symlink guard β or the surviving preset's- # override would be silently skipped (#2948).- for cmd_name in dir_cmds:- for skill_name in self._skill_names_for_command(cmd_name):- if skill_name not in dir_managed_names:- continue- skill_subdir = skills_dir / skill_name- if not self._validate_skill_subdir(- skill_subdir,- create=True,- skills_root=skills_dir,- ):- continue- if is_active:- # Preserve exact prior behaviour for the currently- # active directory (including the ability to create- # brand-new skill subdirectories when ai_skills is on).- written = self._register_skills(filtered_manifest, pack_dir)- else:- written = self._register_skills(- filtered_manifest, pack_dir,- target_dir=skills_dir, target_agent=dir_agent or "",- )- if target_agent is None:- written_names = {- name- for names in written.values()- for name in names- }- else:- written_names = set(written.get(target_agent, []))- for cmd_name in dir_cmds:- if written_names.intersection(- self._skill_names_for_command(cmd_name)- ):- reconciled_skill_commands.add(cmd_name)- # The winning preset may not have previously written to- # this directory's agent (most notably a historical agent- # reconciliation just restored content into via- # extra_skills_dirs). If that write isn't merged back into- # the preset's own registered_skills, its registry entry- # silently lies about which directories it owns and a- # later removal of this same preset orphans the directory- # reconciliation just wrote to on its behalf (#2948).- self._merge_pack_registered_skills(pack_id, written)-- extra_dirs = extra_skills_dirs or {}- if active_skills_dir:- active_provenance = extra_dirs.get(active_skills_dir)- if extra_skills_dirs is None or active_provenance:- apply_to_dir(- active_skills_dir,- active_ai,- is_active=True,- managed_names=(- set(active_provenance[1])- if active_provenance- else None- ),- )-- for extra_dir, (extra_agent, extra_names) in extra_dirs.items():- if extra_dir == active_skills_dir:- continue # already reconciled above as the active directory- apply_to_dir(- extra_dir,- extra_agent,- is_active=False,- managed_names=set(extra_names),- )-- return reconciled_skill_commands-- def _resolve_agent_skills_dir(self, agent_name: str) -> Path:- """Resolve the real skill output directory for an integration."""- from .. import _get_skills_dir as _project_skills_dir- from ..agents import CommandRegistrar-- registrar = CommandRegistrar()- agent_config = registrar.AGENT_CONFIGS.get(agent_name)- if agent_config and agent_config.get("extension") == "/SKILL.md":- return registrar._resolve_agent_dir(- agent_name, agent_config, self.project_root- )- return _project_skills_dir(self.project_root, agent_name)-- def _skills_validation_root(self, skills_dir: Path) -> Optional[Path]:- """Return the trusted root containing a project or user skill dir."""- for root in (self.project_root, Path.home()):- if skills_dir.is_relative_to(root):- return root- return None-- def _get_skills_dir(self) -> Optional[Path]:- """Return the active skills directory for preset skill overrides.-- Uses :func:`resolve_active_skills_dir` for activation/detection,- then resolves native skill agents through the registrar's output- directory so integrations such as Hermes write to their global- skills path rather than their project-local detection marker.-- Returns ``None`` (instead of raising) when the directory cannot- be created due to symlink, containment, or permission issues so- that callers can fall back gracefully.- """- from .. import (- _print_cli_warning,- load_init_options,- resolve_active_skills_dir,- )- from ..shared_infra import _ensure_safe_shared_directory- try:- skills_dir = resolve_active_skills_dir(self.project_root)- except (ValueError, OSError) as exc:- _print_cli_warning(- "resolve", "skills directory", None, exc,- continuing="Continuing without skill registration.",- )- return None- if skills_dir is None:- return None-- opts = load_init_options(self.project_root)- selected_ai = opts.get("ai") if isinstance(opts, dict) else None- if not isinstance(selected_ai, str) or not selected_ai:- return skills_dir-- agent_skills_dir = self._resolve_agent_skills_dir(selected_ai)- if agent_skills_dir == skills_dir:- return skills_dir-- validation_root = self._skills_validation_root(agent_skills_dir)- if validation_root is None:- _print_cli_warning(- "resolve",- "skills directory",- str(agent_skills_dir),- ValueError("skills directory is outside trusted roots"),- continuing="Continuing without skill registration.",- )- return None- try:- _ensure_safe_shared_directory(- validation_root,- agent_skills_dir,- context="preset skills directory",- )- except (ValueError, OSError) as exc:- _print_cli_warning(- "resolve", "skills directory", str(agent_skills_dir), exc,- continuing="Continuing without skill registration.",- )- return None- return agent_skills_dir-- @staticmethod- def _skill_names_for_command(cmd_name: str) -> tuple[str, str]:- """Return the modern and legacy skill directory names for a command."""- raw_short_name = cmd_name- if raw_short_name.startswith("speckit."):- raw_short_name = raw_short_name[len("speckit."):]-- modern_skill_name = f"speckit-{raw_short_name.replace('.', '-')}"- legacy_skill_name = f"speckit.{raw_short_name}"- return modern_skill_name, legacy_skill_name-- @staticmethod- def _skill_title_from_command(cmd_name: str) -> str:- """Return a human-friendly title for a skill command name."""- title_name = cmd_name- if title_name.startswith("speckit."):- title_name = title_name[len("speckit."):]- return title_name.replace(".", " ").replace("-", " ").title()-- @staticmethod- def _resolve_skill_command_refs(- body: str,- registrar: "CommandRegistrar",- selected_ai: str,- project_root: "Path | None" = None,- ) -> str:- """Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.-- Looks up the agent's invoke separator and rewrites each- ``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching- agent-native invocation -- ``/speckit-<cmd>`` or ``$speckit-<cmd>`` for- a ``-`` separator, ``/speckit.<cmd>`` for ``.``, or- ``/skill:speckit-<cmd>`` for skill-colon agents (e.g. Kimi) -- the- same rendering the command layer applies via- ``CommandRegistrar.register_commands()``.-- For dual-layout agents (e.g. Bob) the separator depends on the- project's persisted skills state, so -- when *project_root* is provided- -- the separator is resolved from the integration via- ``invoke_separator_for_mode`` rather than the single static- ``AGENT_CONFIGS`` value.- """- separator = None- if project_root is not None and isinstance(selected_ai, str):- try:- from .. import load_init_options- from ..integrations import get_integration-- integration = get_integration(selected_ai)- if integration is not None:- separator = integration.invoke_separator_for_mode(- is_ai_skills_enabled(load_init_options(project_root))- )- except Exception:- separator = None- if separator is None:- separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(- "invoke_separator", "."- )- prefix = get_invocation_prefix(selected_ai, separator == "-")- return IntegrationBase.resolve_command_refs(body, separator, prefix)-- def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:- """Index extension-backed skill restore data by skill directory name."""- from ..extensions import ExtensionManifest, ValidationError-- resolver = PresetResolver(self.project_root)- extensions_dir = self.project_root / ".specify" / "extensions"- restore_index: Dict[str, Dict[str, Any]] = {}-- for _priority, ext_id, _metadata in resolver._get_all_extensions_by_priority():- ext_dir = extensions_dir / ext_id- manifest_path = ext_dir / "extension.yml"- if not manifest_path.is_file():- continue-- try:- manifest = ExtensionManifest(manifest_path)- except (ValidationError, TypeError, AttributeError):- continue-- ext_root = ext_dir.resolve()- for cmd_info in manifest.commands:- cmd_name = cmd_info.get("name")- cmd_file_rel = cmd_info.get("file")- if not isinstance(cmd_name, str) or not isinstance(cmd_file_rel, str):- continue-- cmd_path = Path(cmd_file_rel)- if cmd_path.is_absolute():- continue-- try:- source_file = (ext_root / cmd_path).resolve()- source_file.relative_to(ext_root)- except (OSError, ValueError):- continue-- if not source_file.is_file():- continue-- restore_info = {- "command_name": cmd_name,- "source_file": source_file,- "source": f"extension:{manifest.id}",- "author": manifest.data["extension"].get("author"),- "extension_id": manifest.id,- "extension_dir": ext_root,- }- modern_skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)- restore_index.setdefault(modern_skill_name, restore_info)- if legacy_skill_name != modern_skill_name:- restore_index.setdefault(legacy_skill_name, restore_info)-- return restore_index-- def _register_skills(- self,- manifest: "PresetManifest",- preset_dir: Path,- *,- target_dir: Optional[Path] = None,- target_agent: Optional[str] = None,- ) -> Dict[str, List[str]]:- """Generate SKILL.md files for preset command overrides.-- For every command template in the preset, checks whether a- corresponding skill already exists in any detected skills- directory. If so, the skill is overwritten with content derived- from the preset's command file. This ensures that presets that- override commands also propagate to the agentskills.io skill- layer when skills mode was used during project initialisation.-- Args:- manifest: Preset manifest.- preset_dir: Installed preset directory.- target_dir: Explicit skills directory to render into, instead- of resolving the currently active one. Used by- ``_reconcile_skills`` to restore a surviving preset's- override into a historical (currently inactive) agent's- directory that removal of a higher-priority preset just- reverted (#2948).- target_agent: Explicit agent name to render for, paired with- ``target_dir``. When set, skills are only ever restored- into already-tracked directories/names β brand-new skill- subdirectories are never created for a non-active,- explicitly targeted directory (that creation path is only- meaningful for the currently active agent).-- Returns:- ``{agent_name: [skill_name, ...]}`` for the single active- agent skills were written for (empty if none were written),- matching the shape ``registered_commands`` already uses so the- two can be tracked/restored consistently (#2948).- """- command_templates = [- t for t in manifest.templates if t.get("type") == "command"- ]- if not command_templates:- return {}-- # Preset command templates are self-contained and render as skills- # regardless of whether a like-named extension is installed β the same- # rule _register_commands() uses. No ``speckit.<ns>.<cmd>`` name-shape- # filtering; the per-command loop below skips anything without a target- # skill directory.- skills_dir = target_dir if target_dir is not None else self._get_skills_dir()- if not skills_dir:- return {}-- resolver = PresetResolver(self.project_root)-- from .. import SKILL_DESCRIPTIONS, load_init_options- from ..agents import CommandRegistrar- from ..integrations import get_integration- from ..shared_infra import _write_shared_text-- init_opts = load_init_options(self.project_root)- if not isinstance(init_opts, dict):- init_opts = {}- selected_ai = target_agent if target_agent is not None else init_opts.get("ai")- if not isinstance(selected_ai, str) or not selected_ai:- return {}- # A target_dir/target_agent call reconciles an explicitly-known,- # already-tracked directory (see _reconcile_skills) rather than the- # currently active agent, so ai_skills_enabled must not be derived- # from the *current* project-wide toggle for that other agent β it- # only controls whether brand-new skill subdirectories may be- # created below, which is only meaningful for the active agent.- ai_skills_enabled = target_agent is None and is_ai_skills_enabled(init_opts)- registrar = CommandRegistrar()- integration = get_integration(selected_ai)- agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})- # Native skill agents (e.g. codex/kimi/agy/trae) materialize brand-new- # preset skills in _register_commands() because their detected agent- # directory is already the skills directory. This flag is only for- # command-backed agents that also mirror commands into skills.- create_missing_skills = ai_skills_enabled and agent_config.get("extension") != "/SKILL.md"-- written: List[str] = []-- for cmd_tmpl in command_templates:- cmd_name = cmd_tmpl["name"]- cmd_file_rel = cmd_tmpl["file"]- source_file = preset_dir / cmd_file_rel- if not source_file.exists():- continue-- # Use composed content if available (written by _register_commands- # for commands with non-replace strategies), otherwise the original.- composed_file = preset_dir / ".composed" / f"{cmd_name}.md"- if composed_file.exists():- source_file = composed_file-- # Derive the short command name (e.g. "specify" from "speckit.specify")- raw_short_name = cmd_name- if raw_short_name.startswith("speckit."):- raw_short_name = raw_short_name[len("speckit."):]- short_name = raw_short_name.replace(".", "-")- skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)- skill_title = self._skill_title_from_command(cmd_name)-- # Only overwrite skills that already exist under skills_dir,- # including Kimi native skills when ai_skills is false.- # If both modern and legacy directories exist, update both.- target_skill_names: List[str] = []- if (skills_dir / skill_name).is_dir():- target_skill_names.append(skill_name)- if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():- target_skill_names.append(legacy_skill_name)- if not target_skill_names and create_missing_skills:- missing_skill_dir = skills_dir / skill_name- if not missing_skill_dir.exists():- target_skill_names.append(skill_name)- if not target_skill_names:- continue-- # Parse the command file- content = source_file.read_text(encoding="utf-8")- frontmatter, body = registrar.parse_frontmatter(content)-- # A composition-strategy command (wrap/prepend/append) needs a- # base layer to compose onto. When _register_commands produced no- # composed file for it and the stack still has no base- # (resolve_content is None) β e.g. the command it wraps comes from- # an extension that isn't installed β rendering the raw preset- # fragment as a skill would emit broken output: a literal- # {CORE_TEMPLATE} for wrap, or only the preset's own fragment for- # prepend/append. Skip it here too so command mode and skills mode- # agree (mirrors _register_commands, which skips the same command).- # _register_commands already warned for this command in the same- # pass, so the skip is silent here to avoid a duplicate warning.- effective_strategy = (- cmd_tmpl.get("strategy")- or frontmatter.get("strategy")- or "replace"- )- if (- effective_strategy != "replace"- and not composed_file.exists()- and resolver.resolve_content(cmd_name, "command") is None- ):- continue-- if frontmatter.get("strategy") == "wrap":- body, core_frontmatter = _substitute_core_template(body, cmd_name, self.project_root, registrar)- frontmatter = dict(frontmatter)- for key in ("scripts", "agent_scripts", "argument-hint"):- if key not in frontmatter and key in core_frontmatter:- frontmatter[key] = core_frontmatter[key]-- original_desc = frontmatter.get("description", "")- enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(- short_name,- f"Spec-kit workflow command: {short_name}",- )- frontmatter = dict(frontmatter)- frontmatter["description"] = enhanced_desc- body = registrar.resolve_skill_placeholders(- selected_ai, frontmatter, body, self.project_root- )- body = self._resolve_skill_command_refs(body, registrar, selected_ai, self.project_root)-- for target_skill_name in target_skill_names:- skill_subdir = skills_dir / target_skill_name- if skill_subdir.exists() and not skill_subdir.is_dir():- continue- # Validate (and create, if missing) the skill's own- # subdirectory under the same symlink guard as its parent β- # is_dir() above follows symlinks, so a symlinked subdir- # with a real parent would otherwise slip through and have- # SKILL.md written through it to an arbitrary location (#2948).- if not self._validate_skill_subdir(- skill_subdir, create=True, skills_root=skills_dir- ):- continue- frontmatter_data = registrar.build_skill_frontmatter(- selected_ai,- target_skill_name,- enhanced_desc,- f"preset:{manifest.id}",- )- registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)- frontmatter_text = dump_frontmatter(frontmatter_data)- skill_content = (- f"---\n"- f"{frontmatter_text}\n"- f"---\n\n"- f"# Speckit {skill_title} Skill\n\n"- f"{body}\n"- )- if integration is not None and hasattr(integration, "post_process_skill_content"):- skill_content = integration.post_process_skill_content(- skill_content- )-- skill_file = skill_subdir / "SKILL.md"- _write_shared_text(- skills_dir, skill_file, skill_content- )- written.append(target_skill_name)- self._merge_pack_registered_skills(- manifest.id, {selected_ai: [target_skill_name]}- )-- return {selected_ai: written} if written else {}-- def _infer_legacy_skill_provenance(- self, skill_names: List[str], pack_id: str, fallback_agent: str- ) -> Dict[str, List[str]]:- """Infer per-agent ownership of a legacy flat-list ``registered_skills`` value.-- Pre-#2948 registries recorded ``registered_skills`` as a flat list- with no record of which agent directory each name was actually- written under. Blindly attributing every name to ``fallback_agent``- (the agent currently being processed) loses the real writer whenever- the *first* operation after upgrading is a direct switch to a- *different* agent β e.g. a legacy Copilot override (written while- Copilot was active with ``ai_skills`` enabled) followed directly by- ``integration use claude``, with no intervening rescaffold for- Copilot β permanently orphaning Copilot's override on later- removal.-- Every project-local configured integration's skills directory is probed (via- the same safe, symlink-validated helpers used for- restore/removal), not only agents whose registrar config is- statically ``/SKILL.md``-only: a command-backed agent (e.g.- Copilot, whose command extension is ``.agent.md``) renders its- preset overrides as ``SKILL.md`` files exactly like a native- skill-only agent whenever it was the active agent with- ``ai_skills`` enabled, so excluding it would miss real,- preset-owned provenance and misattribute it to whichever agent- happens to be processed first. Each directory is probed for a- ``SKILL.md`` whose frontmatter records this exact preset as the- owner (``metadata.source == "preset:<pack_id>"``, the same marker- :meth:`_register_skills` writes) β this marker check is what keeps- the broadened probe from falsely attributing ownership to an- agent's directory that never actually held this preset's override- (e.g. a command-mode agent that never rendered skills, or an- unrelated skill of the same name). A name can legitimately be- found under more than one agent's directory β the preset may have- been active while the user switched between several agents before- provenance tracking existed β so every matching agent is recorded,- not just the first. Names that can't be matched to any directory- (e.g. the file was deleted out of band) fall back to- ``fallback_agent``, preserving the previous best-effort behaviour- for the unrecoverable case.- """- from ..agents import CommandRegistrar-- registrar = CommandRegistrar()- candidate_agents = sorted(registrar.AGENT_CONFIGS)-- # Multiple agent names can resolve to the same physical directory- # (e.g. agy/amp/codex/zed all use .agents/skills); group by- # directory so each is probed once and attributed to a single- # deterministic canonical agent name, matching the tie-break- # already used by _unregister_skills's directory grouping. Deliberately- # keep the unresolved path (matching what _safe_skills_dir_for_agent- # already validated) rather than calling .resolve() here: on macOS- # /var is itself a symlink to /private/var, so resolving would make- # this path diverge from self.project_root's own resolution state- # and make every subsequent containment check in- # _validate_skill_subdir() spuriously fail.- dir_to_agents: Dict[Path, List[str]] = {}- for agent_name in candidate_agents:- skills_dir = self._safe_skills_dir_for_agent(agent_name)- if skills_dir is None:- continue- # Only project-local skills directories are eligible: the- # legacy provenance markers don't record which project owns a- # skill under a home directory, so deletion stays restricted- # to the project root. Revisit if provenance ever records the- # owning project.- if not Path(os.path.abspath(skills_dir)).is_relative_to(- Path(os.path.abspath(self.project_root))- ):- continue- dir_to_agents.setdefault(skills_dir, []).append(agent_name)-- marker = f"preset:{pack_id}"- # Filter unsafe names once, up front, rather than only inside the- # matching loop: any name skipped there would otherwise still- # land in "unmatched" below and get blindly attributed to- # fallback_agent anyway, defeating the guard entirely (#2948).- safe_skill_names = [- name for name in skill_names if self._is_safe_registry_skill_name(name)- ]- inferred: Dict[str, List[str]] = {}- matched_names: set = set()- for resolved_dir, agents in dir_to_agents.items():- canonical_agent = fallback_agent if fallback_agent in agents else sorted(agents)[0]- for name in safe_skill_names:- skill_subdir = resolved_dir / name- if not self._validate_skill_subdir(- skill_subdir, create=False, skills_root=resolved_dir- ):- continue- skill_file = skill_subdir / "SKILL.md"- if not skill_file.is_file():- continue- try:- content = skill_file.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- continue- frontmatter, _ = registrar.parse_frontmatter(content)- skill_metadata = frontmatter.get("metadata")- source = (- skill_metadata.get("source")- if isinstance(skill_metadata, dict)- else None- )- if source == marker:- inferred.setdefault(canonical_agent, []).append(name)- matched_names.add(name)-- unmatched = [name for name in safe_skill_names if name not in matched_names]- if unmatched and fallback_agent:- fallback_names = inferred.setdefault(fallback_agent, [])- for name in unmatched:- if name not in fallback_names:- fallback_names.append(name)-- return inferred-- @staticmethod- def _normalize_registered_skills(- value: Any, fallback_agent: Optional[str] = None- ) -> Dict[str, List[str]]:- """Normalize a ``registered_skills`` registry value to per-agent form.-- The registry stores ``registered_skills`` as ``Dict[str, List[str]]``- (agent name -> skill names actually written for that agent),- mirroring ``registered_commands``. Older registries predate that- provenance and stored a flat ``List[str]`` with no record of which- agent directory the names were written under; since that can't be- recovered, ``fallback_agent`` (when given) attributes the legacy- list to the agent currently being processed so the format- self-migrates on the next write. Without a fallback agent, legacy- lists are dropped rather than guessed at.-- Callers that can identify the owning preset (i.e. have a- ``pack_id``) should prefer :meth:`_infer_legacy_skill_provenance`- for a legacy flat-list value instead, which probes on-disk- provenance rather than assuming ``fallback_agent`` wrote every name.- """- if isinstance(value, dict):- return {- agent: list(names)- for agent, names in value.items()- if isinstance(agent, str) and isinstance(names, list)- }- if isinstance(value, list) and value and fallback_agent:- return {fallback_agent: [n for n in value if isinstance(n, str)]}- return {}-- def _safe_skills_dir_for_agent(self, agent_name: str) -> Optional[Path]:- """Resolve ``agent_name``'s skills directory, validated for safety.-- Unlike :meth:`_get_skills_dir` (which resolves only the *currently- active* integration via init-options), this resolves an arbitrary- agent's directory from persisted provenance so a preset's skill- registrations can be restored/cleaned up under an agent that isn't- currently active. The candidate directory is validated through the- project's shared symlink/containment guard before any file in it is- touched; directories that don't exist or fail validation are- skipped rather than raising.- """- from ..agents import CommandRegistrar- from ..shared_infra import _ensure_safe_shared_directory-- if agent_name not in CommandRegistrar.AGENT_CONFIGS:- return None- skills_dir = self._resolve_agent_skills_dir(agent_name)- validation_root = self._skills_validation_root(skills_dir)- if validation_root is None:- return None- try:- _ensure_safe_shared_directory(- validation_root, skills_dir,- create=False, context="preset skills directory",- )- except (ValueError, OSError):- return None- return skills_dir-- @staticmethod- def _is_safe_registry_skill_name(name: Any) -> bool:- """Validate a registry-provided skill name is a single safe path component.-- ``registered_skills`` entries are persisted registry data, not- derived from the current preset manifest, so a corrupted or- maliciously edited registry could contain an absolute path, a- multi-segment path (containing ``/`` or ``\\``), or a traversal- component (``"."``/``".."``) instead of a plain skill directory- name. Any of these β if joined directly onto a skills directory β- can escape the intended skill subtree while still resolving to a- location inside the project root, which is enough to pass the- parent-directory containment/symlink check alone (#2948). This- centralizes the single boundary check every preset cleanup and- provenance loop that consumes registry-provided skill names must- apply before ever constructing a path from one.- """- if not isinstance(name, str) or not name:- return False- if name in (".", ".."):- return False- candidate = Path(name)- if candidate.is_absolute():- return False- if len(candidate.parts) != 1:- return False- if candidate.name != name:- return False- return True-- def _validate_skill_subdir(- self,- skill_subdir: Path,- *,- create: bool,- skills_root: Optional[Path] = None,- ) -> bool:- """Validate a single skill's subdirectory is symlink-free.-- Unlike :meth:`_safe_skills_dir_for_agent` (which only validates the- *parent* skills directory), this validates the skill's own- subdirectory β e.g. ``.claude/skills/speckit-specify`` β so a- symlink planted at that level (with a safe parent) can't be used to- write or delete through to a location outside the project. Shared by- both the registration path (``create=True``, so a missing directory- is created component-by-component under the same guard) and the- restore/removal path (``create=False``, so a missing directory is- left for the caller's own existence check to skip). Returns- ``False`` rather than raising when the path escapes the project- root or crosses a symlink. ``skills_root`` supplies the trusted- agent output boundary for native global skill integrations such as- Hermes; project-local callers default to ``self.project_root``.- """- from ..shared_infra import _ensure_safe_shared_directory, _validate_safe_shared_directory-- validation_root = skills_root or self.project_root- if validation_root.is_symlink():- return False- try:- if create:- _ensure_safe_shared_directory(- validation_root, skill_subdir,- create=True, context="preset skill directory",- )- else:- _validate_safe_shared_directory(- validation_root, skill_subdir- )- except (ValueError, OSError):- return False- return True-- def _unregister_skills(- self,- registered_skills: Union[Dict[str, List[str]], List[str]],- preset_dir: Union[Path, str],- *,- additional_owned_sources: Optional[Dict[str, str]] = None,- restore_from_bundled_core: bool = False,- ) -> Dict[Path, tuple[Optional[str], List[str]]]:- """Restore original SKILL.md files after a preset is removed.-- For each skill that was overridden by the preset, attempts to- regenerate the skill from the core command template. If no core- template exists, the skill directory is removed.-- Args:- restore_from_bundled_core: When True, a missing project-local- core template (the common case β ``specify init`` never- populates ``.specify/templates/commands``) falls back to- the bundled core_pack/repo-root templates so the skill is- restored instead of deleted (#3928). Callers that are- retiring a skill because its command now renders elsewhere- (a command file superseding it) must leave this False so- the skill is removed rather than resurrected with core- content that would duplicate the winning command.-- ``registered_skills`` records exactly which agent directories this- preset actually wrote to (see :meth:`_register_skills`), so removal- restores precisely those directories rather than guessing at every- skill-mode agent that happens to exist on disk. Each directory is- re-resolved and safety-validated at removal time (see- :meth:`_safe_skills_dir_for_agent`) since it may belong to an agent- that isn't currently active.-- Args:- registered_skills: Per-agent skill names written by the preset- (``{agent_name: [skill_name, ...]}``), or a legacy flat- ``List[str]`` from a registry written before this- provenance tracking existed.- preset_dir: The preset's installed directory (may already be deleted).- additional_owned_sources: Generated non-preset source markers- that this cleanup may also replace for specific skill names.-- Returns:- ``{skills_dir: (renderer_agent, managed_skill_names)}`` for- every directory and skill name actually restored or removed.- """- if not registered_skills:- return {}-- pack_id = preset_dir if isinstance(preset_dir, str) else preset_dir.name-- if isinstance(registered_skills, dict):- from .. import load_init_options-- init_opts = load_init_options(self.project_root)- active_agent = init_opts.get("ai") if isinstance(init_opts, dict) else None- if not isinstance(active_agent, str) or not active_agent:- active_agent = None-- # Multiple integration keys can share the same physical- # directory (e.g. agy/codex/zed all resolve to- # ``.agents/skills``). Restoring that directory once per- # recorded agent would have each pass's agent-specific- # rendering (frontmatter, post-processing) overwrite the- # previous one, with whichever agent is iterated *last* silently- # winning regardless of which agent is actually active. Group- # provenance by resolved directory so each physical directory is- # restored exactly once, using the active agent's renderer when- # it shares that directory (otherwise any recorded owner,- # chosen deterministically).- groups: Dict[Path, Dict[str, Any]] = {}- for agent_name, skill_names in registered_skills.items():- if not skill_names:- continue- skills_dir = self._safe_skills_dir_for_agent(agent_name)- if skills_dir is None:- continue- group = groups.setdefault(skills_dir, {"agents": [], "names": []})- group["agents"].append(agent_name)- for name in skill_names:- if (- self._is_safe_registry_skill_name(name)- and name not in group["names"]- ):- group["names"].append(name)-- restored: Dict[Path, tuple[Optional[str], List[str]]] = {}- for skills_dir, group in groups.items():- agents = group["agents"]- renderer_agent = (- active_agent if active_agent in agents else sorted(agents)[0]- )- mutated_names = self._unregister_skills_in_dir(- group["names"],- skills_dir,- renderer_agent,- pack_id=pack_id,- additional_owned_sources=additional_owned_sources,- restore_from_bundled_core=restore_from_bundled_core,- )- if mutated_names:- restored[skills_dir] = (- renderer_agent,- mutated_names,- )- return restored-- # Legacy flat-list format: no record of which agent directory these- # names were written under, so best-effort restore is limited to the- # currently active agent's directory (the pre-provenance behaviour).- skills_dir = self._get_skills_dir()- if not skills_dir:- return {}- from .. import load_init_options-- init_opts = load_init_options(self.project_root)- if not isinstance(init_opts, dict):- init_opts = {}- selected_ai = init_opts.get("ai")- selected_ai = selected_ai if isinstance(selected_ai, str) else None- safe_names = [- name- for name in registered_skills- if self._is_safe_registry_skill_name(name)- ]- mutated_names = self._unregister_skills_in_dir(- safe_names,- skills_dir,- selected_ai,- pack_id=pack_id,- additional_owned_sources=additional_owned_sources,- restore_from_bundled_core=restore_from_bundled_core,- )- return (- {skills_dir: (selected_ai, mutated_names)}- if mutated_names- else {}- )-- def _delete_agent_preset_skills(- self, agent_name: str, skill_names: List[str], pack_id: str- ) -> None:- """Delete still-preset-owned skills when an agent is deactivated."""- skills_dir = self._safe_skills_dir_for_agent(agent_name)- if skills_dir is None:- return-- from ..agents import CommandRegistrar-- registrar = CommandRegistrar()- marker = f"preset:{pack_id}"- override_sources: Dict[str, str] = {}- manifest = PresetResolver(self.project_root)._get_manifest(- self.presets_dir / pack_id- )- if manifest is not None:- for template in manifest.templates:- command_name = template.get("name")- if (- template.get("type") == "command"- and isinstance(command_name, str)- ):- for skill_name in self._skill_names_for_command(- command_name- ):- override_sources[skill_name] = (- f"override:{command_name}"- )- for skill_name in skill_names:- if not self._is_safe_registry_skill_name(skill_name):- continue- skill_subdir = skills_dir / skill_name- if not self._validate_skill_subdir(- skill_subdir, create=False, skills_root=skills_dir- ):- continue- skill_file = skill_subdir / "SKILL.md"- if not skill_file.is_file():- continue- try:- content = skill_file.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- continue- frontmatter, _ = registrar.parse_frontmatter(content)- metadata = frontmatter.get("metadata")- source = (- metadata.get("source")- if isinstance(metadata, dict)- else None- )- owned_sources = {marker}- override_source = override_sources.get(skill_name)- if override_source:- owned_sources.add(override_source)- if source in owned_sources:- shutil.rmtree(skill_subdir)-- @staticmethod- def _warn_unrestored_skill(- skill_name: str, source_file: Path, exc: BaseException- ) -> None:- """Warn that a skill kept preset content because its restore source is unreadable.-- Skipping the restore is the safe recovery β the alternative branch- deletes the skill outright β but it is still a partial removal: the- preset directory and registry entry go away while this ``SKILL.md``- keeps the removed preset's content, and reconciliation never revisits- it because the name is left out of ``mutated_names``. Name the skill- and the source so the condition is actionable instead of silent.- """- import warnings-- warnings.warn(- f"Skill '{skill_name}' still contains the removed preset's content: "- f"its restore source '{source_file}' could not be read "- f"({exc.__class__.__name__}: {exc}). The skill was left in place "- f"rather than deleted. Fix or remove that file and re-run "- f"'specify preset add'/'specify preset remove' to refresh it.",- stacklevel=2,- )-- def _unregister_skills_in_dir(- self,- skill_names: List[str],- skills_dir: Path,- selected_ai: Optional[str],- *,- pack_id: Optional[str] = None,- additional_owned_sources: Optional[Dict[str, str]] = None,- restore_from_bundled_core: bool = False,- ) -> List[str]:- """Restore original SKILL.md files within a single skills directory.-- Args:- skill_names: List of skill names written by the preset.- skills_dir: The skills directory to restore within.- selected_ai: The agent name that owns ``skills_dir``, used for- placeholder resolution and argument-hint formatting.- additional_owned_sources: Generated non-preset source markers- accepted as owned for specific skill names.- restore_from_bundled_core: See ``_unregister_skills``.-- Returns:- Skill names whose files were restored or removed.- """- from .. import SKILL_DESCRIPTIONS- from ..agents import CommandRegistrar- from ..integrations import get_integration- from ..shared_infra import _write_shared_text-- # Locate core command templates from the project's installed templates- core_templates_dir = self.project_root / ".specify" / "templates" / "commands"- registrar = CommandRegistrar()- integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None- extension_restore_index = self._build_extension_skill_restore_index()- mutated_names: List[str] = []-- for skill_name in skill_names:- # Guard against a corrupted/malicious registry entry: a- # registered_skills name is persisted data, not derived from- # the current manifest, so it must be validated as a single,- # relative, non-"."/".." path component before ever being- # joined onto skills_dir. Without this, an absolute name- # discards skills_dir entirely (Path's "/" operator drops the- # left side for an absolute right side) or a multi-component- # name containing ".." can resolve to a different, unrelated- # directory that still happens to be inside the project root- # β passing the containment-only symlink guard below and- # letting removal overwrite/delete it (#2948).- if not self._is_safe_registry_skill_name(skill_name):- continue-- # Derive command name from skill name (speckit-specify -> specify)- short_name = skill_name- if short_name.startswith("speckit-"):- short_name = short_name[len("speckit-"):]- elif short_name.startswith("speckit."):- short_name = short_name[len("speckit."):]-- skill_subdir = skills_dir / skill_name- skill_file = skill_subdir / "SKILL.md"- if not skill_subdir.is_dir():- continue- # is_dir() follows symlinks, so a symlinked skill subdirectory- # (with a safe, non-symlinked parent) would otherwise slip past- # _safe_skills_dir_for_agent's parent-only check and have- # write_text/rmtree operate through it (#2948).- if not self._validate_skill_subdir(- skill_subdir, create=False, skills_root=skills_dir- ):- continue- if not skill_file.is_file():- # Only manage directories that contain the expected skill entrypoint.- continue- if pack_id is not None:- try:- current_content = skill_file.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- continue- current_frontmatter, _ = registrar.parse_frontmatter(current_content)- current_metadata = current_frontmatter.get("metadata")- current_source = (- current_metadata.get("source")- if isinstance(current_metadata, dict)- else None- )- owned_sources = {f"preset:{pack_id}"}- if additional_owned_sources:- additional_source = additional_owned_sources.get(- skill_name- )- if additional_source:- owned_sources.add(additional_source)- if current_source not in owned_sources:- continue-- extension_restore = extension_restore_index.get(skill_name)-- # Try to find the core command template. Project-local overrides- # in core_templates_dir take precedence, but that directory is- # rarely populated β the real core commands ship in the bundled- # core_pack (wheel install) or the repo-root templates/ tree- # (source checkout). Callers that want a genuine restore (a- # preset was removed outright, not superseded by another- # renderer) opt into that fallback via restore_from_bundled_core- # so the skill is restored instead of deleted (#3928). An- # installed extension providing a core-named command resolves- # ahead of bundled core elsewhere, so skip the bundled fallback- # when an extension restore exists β otherwise it would win- # over the higher-priority extension layer below.- core_file = core_templates_dir / f"{short_name}.md"- if (- not core_file.exists()- and restore_from_bundled_core- and extension_restore is None- ):- from .. import _locate_core_pack, _repo_root-- _core_pack = _locate_core_pack()- if _core_pack is not None:- core_file = _core_pack / "commands" / f"{short_name}.md"- else:- core_file = _repo_root() / "templates" / "commands" / f"{short_name}.md"- if not core_file.exists():- core_file = None-- if core_file:- # Restore from core template. An unreadable/undecodable- # source cannot produce restored content, so leave the- # existing skill untouched rather than leaking a raw- # OSError/UnicodeDecodeError out of `preset remove` β and- # rather than falling through to the rmtree below, which- # would delete a skill precisely when its replacement- # cannot be generated. Matches the `continue` guards above- # (unsafe name, missing subdir, foreign owner), which also- # skip without recording the name as mutated.- try:- content = core_file.read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError) as exc:- self._warn_unrestored_skill(skill_name, core_file, exc)- continue- frontmatter, body = registrar.parse_frontmatter(content)- if isinstance(selected_ai, str):- body = registrar.resolve_skill_placeholders(- selected_ai, frontmatter, body, self.project_root- )- body = self._resolve_skill_command_refs(- body, registrar, selected_ai, self.project_root- )-- original_desc = frontmatter.get("description", "")- enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(- short_name,- f"Spec-kit workflow command: {short_name}",- )-- frontmatter_data = registrar.build_skill_frontmatter(- selected_ai if isinstance(selected_ai, str) else "",- skill_name,- enhanced_desc,- f"templates/commands/{short_name}.md",- )- registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)- frontmatter_text = dump_frontmatter(frontmatter_data)- skill_title = self._skill_title_from_command(short_name)- skill_content = (- f"---\n"- f"{frontmatter_text}\n"- f"---\n\n"- f"# Speckit {skill_title} Skill\n\n"- f"{body}\n"- )- if integration is not None and hasattr(integration, "post_process_skill_content"):- skill_content = integration.post_process_skill_content(- skill_content- )- _write_shared_text(skills_dir, skill_file, skill_content)- mutated_names.append(skill_name)- continue-- if extension_restore:- # Same boundary as the core-template branch above: an- # unreadable extension source leaves the skill in place- # instead of crashing or being deleted.- try:- content = extension_restore["source_file"].read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError) as exc:- self._warn_unrestored_skill(- skill_name, extension_restore["source_file"], exc- )- continue- frontmatter, body = registrar.parse_frontmatter(content)- # Mirror the register-time rewrite (#2101): resolve- # extension-relative subdir references (agents/,- # knowledge-base/, etc.) to their installed location before- # the generic placeholder resolution below, otherwise- # restoring after a preset override removal would leave- # bare, unresolvable paths in the skill body.- body = registrar.rewrite_extension_paths(- body,- extension_restore["extension_id"],- extension_restore["extension_dir"],- )- if isinstance(selected_ai, str):- body = registrar.resolve_skill_placeholders(- selected_ai, frontmatter, body, self.project_root- )- body = self._resolve_skill_command_refs(- body, registrar, selected_ai, self.project_root- )-- command_name = extension_restore["command_name"]- title_name = self._skill_title_from_command(command_name)-- frontmatter_data = registrar.build_skill_frontmatter(- selected_ai if isinstance(selected_ai, str) else "",- skill_name,- frontmatter.get("description", f"Extension command: {command_name}"),- extension_restore["source"],- author=extension_restore.get("author", "github-spec-kit"),- )- registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)- frontmatter_text = dump_frontmatter(frontmatter_data)- skill_content = (- f"---\n"- f"{frontmatter_text}\n"- f"---\n\n"- f"# {title_name} Skill\n\n"- f"{body}\n"- )- if integration is not None and hasattr(integration, "post_process_skill_content"):- skill_content = integration.post_process_skill_content(- skill_content- )- _write_shared_text(skills_dir, skill_file, skill_content)- mutated_names.append(skill_name)- else:- # No core or extension template β remove the skill entirely- shutil.rmtree(skill_subdir)- mutated_names.append(skill_name)-- return mutated_names-- def install_from_directory(- self,- source_dir: Path,- speckit_version: str,- priority: int = 10,- force: bool = False,- *,- catalog_name: str | None = None,- ) -> PresetManifest:- """Install preset from a local directory.-- Args:- source_dir: Path to preset directory- speckit_version: Current spec-kit version- priority: Resolution priority (lower = higher precedence, default 10)- force: If True and the preset is already installed, remove it first-- Returns:- Installed preset manifest-- Raises:- PresetValidationError: If manifest is invalid or priority is invalid- PresetCompatibilityError: If pack is incompatible- """- # Validate priority- if priority < 1:- raise PresetValidationError("Priority must be a positive integer (1 or higher)")-- manifest_path = source_dir / "preset.yml"- manifest = PresetManifest(manifest_path)-- self.check_compatibility(manifest, speckit_version)-- if self.registry.is_installed(manifest.id):- if not force:- raise PresetError(- f"Preset '{manifest.id}' is already installed. "- f"Use 'specify preset remove {manifest.id}' first."- )- self.remove(manifest.id)-- dest_dir = self.presets_dir / manifest.id- if dest_dir.exists():- shutil.rmtree(dest_dir)-- shutil.copytree(source_dir, dest_dir)-- # Pre-register the preset so that composition resolution can see it- # in the priority stack when resolving composed command content.- normalized_catalog_name = (- catalog_name.strip() if isinstance(catalog_name, str) else ""- )- source = (- {"kind": "catalog", "catalog": normalized_catalog_name}- if normalized_catalog_name- else "local"- )- self.registry.add(manifest.id, {- "version": manifest.version,- "source": source,- "manifest_hash": manifest.get_hash(),- "enabled": True,- "priority": priority,- "registered_commands": {},- "registered_skills": {},- })-- registered_commands: Dict[str, List[str]] = {}- registered_skills: Dict[str, List[str]] = {}- try:- # Register command overrides with AI agents and persist the result- # immediately so cleanup can recover even if installation stops- # before later phases complete.- registered_commands = self._register_commands(manifest, dest_dir)- self.registry.update(manifest.id, {- "registered_commands": registered_commands,- })-- # Update corresponding skills when skills mode was previously used- # and persist that result as well.- registered_skills = self._register_skills(manifest, dest_dir)- self.registry.update(manifest.id, {- "registered_skills": registered_skills,- })- except Exception:- # Roll back all side effects. _register_skills persists each- # successful write immediately, so reload that partial map when- # a later template fails before the call can return.- if registered_commands:- self._unregister_commands(registered_commands)- persisted_metadata = self.registry.get(manifest.id) or {}- persisted_skills = persisted_metadata.get(- "registered_skills", registered_skills- )- if persisted_skills:- self._unregister_skills(- persisted_skills, dest_dir, restore_from_bundled_core=True- )- try:- if dest_dir.exists():- shutil.rmtree(dest_dir)- except OSError:- pass # best-effort cleanup; don't mask the original error- self.registry.remove(manifest.id)- raise-- # Reconcile all affected commands from the full priority stack so that- # install order doesn't determine the winning command file.- cmd_names = [- t["name"]- for t in manifest.templates- if t.get("type") == "command"- ]- if cmd_names:- try:- self._reconcile_composed_commands(cmd_names)- self._reconcile_skills(cmd_names)- except Exception as exc:- import warnings- warnings.warn(- f"Post-install reconciliation failed for {manifest.id}: {exc}. "- f"Agent command files may not reflect the current priority stack.",- stacklevel=2,- )-- # Materialize constitution-template changes only for projects that opt- # into the constitution-sync preset. The core /constitution command- # resolves this template on demand; constitution-sync preserves the- # previous install-time behavior for teams that want reviewed snapshots.- self._seed_constitution_from_preset(manifest, dest_dir)-- return manifest-- def _seed_constitution_from_preset(- self, manifest: PresetManifest, preset_dir: Path- ) -> None:- """Seed memory/constitution.md when constitution-sync opts into snapshots.-- Installing constitution-sync itself materializes the currently resolved- stack. Later preset installs only reconcile when they provide a- ``constitution-template``. Authored constitutions are never overwritten.- """- provides_constitution = manifest.id == _CONSTITUTION_SYNC_PRESET_ID or any(- t.get("type") == "template" and t.get("name") == "constitution-template"- for t in manifest.templates- ) or any(- (preset_dir / relative_path).is_file()- for relative_path in (- "templates/constitution-template.md",- "constitution-template.md",- )- )- if not provides_constitution:- return-- self.reconcile_constitution(- f"Failed to seed constitution from preset {manifest.id}",- create_if_missing=True,- )-- def reconcile_constitution(- self, failure_context: str, *, create_if_missing: bool = False- ) -> None:- """Reconcile an opted-in generated constitution without failing a change."""- try:- self._reconcile_constitution(create_if_missing=create_if_missing)- except (OSError, UnicodeDecodeError, PresetValidationError, ValueError) as exc:- import warnings-- warnings.warn(- f"{failure_context}: {exc}.",- stacklevel=2,- )-- def _reconcile_constitution(self, *, create_if_missing: bool = False) -> None:- """Materialize the winning layer when constitution-sync is enabled."""- sync_metadata = self.registry.get(_CONSTITUTION_SYNC_PRESET_ID)- if sync_metadata is None or not sync_metadata.get("enabled", True):- return-- memory_constitution = (- self.project_root / ".specify" / "memory" / "constitution.md"- )- if not memory_constitution.exists() and not create_if_missing:- return- resolver = PresetResolver(self.project_root)- if memory_constitution.exists() and not _constitution_is_generated(- self.project_root, memory_constitution, resolver- ):- return- _materialize_constitution_template(self.project_root, memory_constitution)-- def install_from_archive(- self,- archive_path: Path,- speckit_version: str,- priority: int = 10,- force: bool = False,- *,- catalog_name: str | None = None,- ) -> PresetManifest:- """Install a preset from a supported archive.-- Args:- archive_path: Path to a .zip, .tar.gz, or .tgz archive- speckit_version: Current spec-kit version- priority: Resolution priority (lower = higher precedence, default 10)- force: If True and the preset is already installed, remove it first-- Returns:- Installed preset manifest-- Raises:- PresetValidationError: If manifest is invalid or priority is invalid- PresetCompatibilityError: If pack is incompatible- """- # Validate priority early- if priority < 1:- raise PresetValidationError("Priority must be a positive integer (1 or higher)")-- with tempfile.TemporaryDirectory() as tmpdir:- temp_path = Path(tmpdir)-- safe_extract_archive(- archive_path,- temp_path,- error_type=PresetValidationError,- )-- pack_dir = temp_path- manifest_path = pack_dir / "preset.yml"-- if not manifest_path.exists():- subdirs = [d for d in temp_path.iterdir() if d.is_dir()]- if len(subdirs) == 1:- pack_dir = subdirs[0]- manifest_path = pack_dir / "preset.yml"-- if not manifest_path.exists():- raise PresetValidationError(- "No preset.yml found in archive"- )-- return self.install_from_directory(- pack_dir,- speckit_version,- priority,- force=force,- catalog_name=catalog_name,- )-- def install_from_zip(- self,- zip_path: Path,- speckit_version: str,- priority: int = 10,- force: bool = False,- *,- catalog_name: str | None = None,- ) -> PresetManifest:- """Backward-compatible wrapper for archive installation."""- return self.install_from_archive(- zip_path,- speckit_version,- priority,- force=force,- catalog_name=catalog_name,- )-- def remove(self, pack_id: str) -> bool:- """Remove an installed preset.-- Args:- pack_id: Preset ID-- Returns:- True if pack was removed- """- if not self.registry.is_installed(pack_id):- return False-- metadata = self.registry.get(pack_id)- # Restore original skills when preset is removed- registered_skills = metadata.get("registered_skills", []) if metadata else []- if isinstance(registered_skills, list) and registered_skills:- # Legacy flat-list registries predate per-agent provenance- # tracking. Migration to the per-agent dict form previously- # only happened during a rescaffold (register_enabled_presets_- # for_agent); if the *first* post-upgrade operation is instead- # `preset remove` (no intervening use/upgrade), the legacy- # branch of _unregister_skills restores only the currently- # active agent's directory, leaving this preset's overrides in- # every previously active agent's directory orphaned. Infer- # real per-agent ownership from the on-disk preset marker now,- # while pack_id is still known, and hand the resulting mapping- # through the same dict-based cleanup path already used for- # non-legacy registries (#2948).- from .. import load_init_options-- init_opts = load_init_options(self.project_root)- fallback_agent = init_opts.get("ai") if isinstance(init_opts, dict) else None- if not isinstance(fallback_agent, str):- fallback_agent = ""- registered_skills = self._infer_legacy_skill_provenance(- [name for name in registered_skills if isinstance(name, str)],- pack_id,- fallback_agent=fallback_agent,- )- registered_commands = metadata.get("registered_commands", {}) if metadata else {}- pack_dir = self.presets_dir / pack_id-- # Record which historical agents this preset's registered_commands- # actually targeted, *before* any filtering below, so post-removal- # reconciliation can restore a surviving lower-priority preset's- # override into every one of those directories too β not only the- # currently active agent's. Without this, removing a preset that- # was rendered under a previously-active (now inactive) agent- # deletes that agent's command file via _unregister_commands below,- # but active-only reconciliation would only recreate the surviving- # winner for the current agent, leaving the inactive integration- # with a missing/stale file (#2948).- try:- from ..agents import CommandRegistrar as _CommandRegistrarForScope- except ImportError:- _CommandRegistrarForScope = None- affected_command_agents = {- agent_name- for agent_name in registered_commands- if _CommandRegistrarForScope is None- or _CommandRegistrarForScope.AGENT_CONFIGS.get(agent_name, {}).get("extension") != "/SKILL.md"- }-- # Collect ALL command names before filtering for reconciliation,- # so commands registered only for skill-based agents are also- # reconciled. Every command-type template's primary name is added- # unconditionally (not just aliases) since ai_skills-mode presets- # never populate registered_commands for command-backed- # integrations (see _register_commands's ai_skills guard) β without- # this, removing a skills-mode preset that overrides a command no- # other preset registered "the normal way" would skip reconciliation- # entirely and _unregister_skills would restore core/extension- # content instead of a surviving lower-priority preset's override.- removed_cmd_names = set()- removed_constitution = any(- path.exists()- for path in (- pack_dir / "templates" / "constitution-template.md",- pack_dir / "constitution-template.md",- )- )- if metadata and isinstance(metadata.get("version"), str):- memory_constitution = (- self.project_root / ".specify" / "memory" / "constitution.md"- )- removed_constitution = removed_constitution or (- _constitution_provenance_matches_preset(- self.project_root,- memory_constitution,- pack_id,- metadata["version"],- )- )- for cmd_names in registered_commands.values():- removed_cmd_names.update(cmd_names)- manifest_path = pack_dir / "preset.yml"- if manifest_path.exists():- try:- manifest = PresetManifest(manifest_path)- for tmpl in manifest.templates:- if (- tmpl.get("type") == "template"- and tmpl.get("name") == "constitution-template"- ):- removed_constitution = True- if tmpl.get("type") == "command":- name = tmpl.get("name")- if isinstance(name, str):- removed_cmd_names.add(name)- for alias in tmpl.get("aliases", []):- if isinstance(alias, str):- removed_cmd_names.add(alias)- except PresetValidationError:- # Invalid manifest β skip alias extraction; primary command- # names from registered_commands are still unregistered.- pass-- affected_skill_dirs: Dict[- Path, tuple[Optional[str], List[str]]- ] = {}- if registered_skills:- restorable_skills = registered_skills- # A skill tracked for a command-backed agent whose ai_skills is- # now off is a leftover from a partially failed skillsβcommand- # toggle. Restoring it via _unregister_skills (and letting- # _reconcile_skills reapply a surviving lower preset through- # extra_skills_dirs) would hand the active command-mode agent a- # skill artifact it must not have β its current representation- # is the command file handled via registered_commands above.- # Delete the preset-owned skill instead and keep its directory- # out of restoration/reconciliation entirely (#2948). Inactive- # agents' entries still restore as before.- # The legacy branch above locally imports load_init_options,- # shadowing the module-level name for this whole function.- from .._init_options import load_init_options as _load_init_options-- resolved_active = resolve_active_agent_for_registration(- self.project_root- )- if (- isinstance(registered_skills, dict)- and isinstance(resolved_active, str)- and resolved_active in registered_skills- and _CommandRegistrarForScope is not None- and _CommandRegistrarForScope.AGENT_CONFIGS.get(- resolved_active, {}- ).get("extension") != "/SKILL.md"- and not is_ai_skills_enabled(- _load_init_options(self.project_root)- )- ):- raw_names = registered_skills.get(resolved_active)- stale_names = [- name- for name in (- raw_names if isinstance(raw_names, list) else []- )- if isinstance(name, str)- ]- restorable_skills = {- agent_name: names- for agent_name, names in registered_skills.items()- if agent_name != resolved_active- }- if stale_names:- self._delete_agent_preset_skills(- resolved_active, stale_names, pack_id- )- override_sources = {- skill_name: f"override:{command_name}"- for command_name in removed_cmd_names- for skill_name in self._skill_names_for_command(command_name)- }- affected_skill_dirs = self._unregister_skills(- restorable_skills,- pack_dir,- additional_owned_sources=override_sources,- restore_from_bundled_core=True,- )- try:- from ..agents import CommandRegistrar- except ImportError:- CommandRegistrar = None- if CommandRegistrar is not None:- skill_coverage = (- registered_skills- if isinstance(registered_skills, dict)- else {}- )- commands_to_unregister: Dict[str, List[str]] = {}- for agent_name, cmd_names in registered_commands.items():- is_native_skill_agent = (- CommandRegistrar.AGENT_CONFIGS.get(- agent_name, {}- ).get("extension")- == "/SKILL.md"- )- if not is_native_skill_agent:- commands_to_unregister[agent_name] = cmd_names- continue-- raw_skill_names = skill_coverage.get(agent_name, [])- covered_skill_names = {- name- for name in (- raw_skill_names- if isinstance(raw_skill_names, list)- else []- )- if isinstance(name, str)- }- uncovered_commands = [- cmd_name- for cmd_name in cmd_names- if not isinstance(cmd_name, str)- or covered_skill_names.isdisjoint(- self._skill_names_for_command(cmd_name)- )- ]- if uncovered_commands:- commands_to_unregister[agent_name] = (- uncovered_commands- )- registered_commands = commands_to_unregister-- # Unregister non-skill command files from AI agents.- if registered_commands:- self._unregister_commands(registered_commands)-- if pack_dir.exists():- shutil.rmtree(pack_dir)-- self.registry.remove(pack_id)-- # Reconcile: if other presets still provide these commands,- # re-resolve from the remaining stack so the next layer takes effect.- if removed_cmd_names:- try:- self._reconcile_composed_commands(- list(removed_cmd_names), extra_agents=affected_command_agents- )- self._reconcile_skills(- list(removed_cmd_names), extra_skills_dirs=affected_skill_dirs- )- except Exception as exc:- import warnings- warnings.warn(- f"Post-removal reconciliation failed for {pack_id}: {exc}. "- f"Agent command files may be stale; reinstall affected presets "- f"or run 'specify preset add' to refresh.",- stacklevel=2,- )-- if removed_constitution:- try:- self._reconcile_constitution()- except (OSError, UnicodeDecodeError, PresetValidationError, ValueError) as exc:- import warnings-- warnings.warn(- f"Post-removal constitution reconciliation failed for {pack_id}: "- f"{exc}. The live constitution may be stale.",- stacklevel=2,- )-- return True-- def list_installed(self) -> List[Dict[str, Any]]:- """List all installed presets with metadata.-- Returns:- List of preset metadata dictionaries- """- result = []-- for pack_id, metadata in self.registry.list().items():- # Ensure metadata is a dictionary to avoid AttributeError when using .get()- if not isinstance(metadata, dict):- metadata = {}- pack_dir = self.presets_dir / pack_id- manifest_path = pack_dir / "preset.yml"-- try:- manifest = PresetManifest(manifest_path)- provided_counts = {"commands": 0, "templates": 0, "scripts": 0, "hooks": 0}- for template in manifest.templates:- provided_counts[f"{template['type']}s"] += 1- author = manifest.author- result.append({- "id": pack_id,- "name": manifest.name,- "version": metadata.get("version", manifest.version),- "description": manifest.description,- "enabled": metadata.get("enabled", True),- "installed_at": metadata.get("installed_at"),- "template_count": len(manifest.templates),- "tags": manifest.tags,- "priority": normalize_priority(metadata.get("priority")),- "_json_author": author if isinstance(author, str) and author else None,- "_json_source": metadata.get("source"),- "_json_provides": provided_counts,- })- except PresetValidationError:- result.append({- "id": pack_id,- "name": pack_id,- "version": metadata.get("version", "unknown"),- "description": "β οΈ Corrupted preset",- "enabled": False,- "installed_at": metadata.get("installed_at"),- "template_count": 0,- "tags": [],- "priority": normalize_priority(metadata.get("priority")),- "_json_author": None,- "_json_source": metadata.get("source"),- "_json_provides": {"commands": 0, "templates": 0, "scripts": 0, "hooks": 0},- })-- return result-- def get_pack(self, pack_id: str) -> Optional[PresetManifest]:- """Get manifest for an installed preset.-- Args:- pack_id: Preset ID-- Returns:- Preset manifest or None if not installed- """- if not self.registry.is_installed(pack_id):- return None-- pack_dir = self.presets_dir / pack_id- manifest_path = pack_dir / "preset.yml"-- try:- return PresetManifest(manifest_path)- except PresetValidationError:- return None---class PresetCatalog:- """Manages preset catalog fetching, caching, and searching.-- Supports multi-catalog stacks with priority-based resolution,- mirroring the extension catalog system.- """-- DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.json"- COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json"- CACHE_DURATION = 3600 # 1 hour in seconds-- def __init__(self, project_root: Path):- """Initialize preset catalog manager.-- Args:- project_root: Root directory of the spec-kit project- """- self.project_root = project_root- self.presets_dir = project_root / ".specify" / "presets"- self.cache_dir = self.presets_dir / ".cache"- self.cache_file = self.cache_dir / "catalog.json"- self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"-- def _validate_catalog_url(self, url: str) -> None:- """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).-- Args:- url: URL to validate-- Raises:- PresetValidationError: If URL is invalid or uses non-HTTPS scheme- """- from urllib.parse import urlparse-- try:- parsed = urlparse(url)- hostname = parsed.hostname- # Accessing ``port`` performs urllib's syntax/range validation;- # ``hostname`` alone does not, so a non-numeric or out-of-range- # port would otherwise pass validation here and only fail later,- # at fetch time, as a raw error this function does not translate- # into PresetValidationError. Mirrors specify_cli.catalogs and- # bundler/services/adapters.py's copy of this same guard.- _ = parsed.port- except ValueError:- raise PresetValidationError(f"Catalog URL is malformed: {url}") from None- is_localhost = hostname in ("localhost", "127.0.0.1", "::1")- if parsed.scheme != "https" and not (- parsed.scheme == "http" and is_localhost- ):- raise PresetValidationError(- f"Catalog URL must use HTTPS (got {parsed.scheme}://). "- "HTTP is only allowed for localhost."- )- # Check hostname, not netloc: netloc is truthy for host-less URLs like- # "https://:8080" or "https://user@", so the host guarantee this error- # promises would not actually hold. hostname is None in those cases (#3209).- if not hostname:- raise PresetValidationError(- "Catalog URL must be a valid URL with a host."- )-- def _make_request(self, url: str):- """Build a urllib Request, adding auth headers when a provider matches.-- Delegates to :func:`specify_cli.authentication.http.build_request`.- """- from specify_cli.authentication.http import build_request- return build_request(url)-- def _open_url(- self,- url: str,- timeout: int = 10,- extra_headers: Optional[Dict[str, str]] = None,- redirect_validator=None,- ):- """Open a URL with provider-based auth, trying each configured provider.-- Delegates to :func:`specify_cli.authentication.http.open_url`.- *redirect_validator*, when provided, is invoked as ``(old_url, new_url)``- before EACH redirect hop, so an HTTPS host guarantee can be enforced on- every intermediate URL, not just the terminal one.- """- from specify_cli.authentication.http import open_url- return open_url(- url,- timeout,- extra_headers=extra_headers,- redirect_validator=redirect_validator,- )-- def _resolve_github_release_asset_api_url(- self,- download_url: str,- timeout: int = 60,- ) -> Optional[str]:- """Resolve a GitHub release asset URL to its REST API asset URL.-- Passes the ``github`` provider hosts from ``auth.json`` so GitHub- Enterprise Server release assets resolve via ``/api/v3``.- """- from specify_cli.authentication.github_http import resolve_github_release_asset_api_url- from specify_cli.authentication.http import github_provider_hosts-- return resolve_github_release_asset_api_url(- download_url,- self._open_url,- timeout=timeout,- github_hosts=github_provider_hosts(),- )-- def _validate_catalog_payload(self, catalog_data: Any, url: str) -> None:- """Validate a parsed preset-catalog payload's shape.-- Applied to both network-fetched and cache-loaded payloads so a- once-poisoned cache (older spec-kit version, manual edit, upstream- served a bad payload before the network-side guards were added)- cannot re-crash ``_get_merged_packs`` on subsequent calls.-- Checking only key presence would let a payload like- ``{"presets": []}`` or ``{"presets": null}`` slip through here and- then crash with ``AttributeError: 'list' object has no attribute- 'items'`` deep inside ``_get_merged_packs``. The sibling- integration catalog reader already guards both the root object and- the nested mapping (see ``integrations/catalog.py``); the preset- catalog must stay consistent so a malformed payload surfaces as- the user-facing ``Invalid preset catalog format`` error instead of- a raw Python traceback.-- Args:- catalog_data: Parsed JSON payload from the catalog source.- url: Source URL β used in the error message so the user can- tell which catalog in a multi-catalog stack is malformed.-- Raises:- PresetError: If the payload's shape is invalid.- """- if not isinstance(catalog_data, dict):- raise PresetError(- f"Invalid preset catalog format from {url}: "- "expected a JSON object"- )- if (- "schema_version" not in catalog_data- or "presets" not in catalog_data- ):- raise PresetError(f"Invalid preset catalog format from {url}")- if not isinstance(catalog_data.get("presets"), dict):- raise PresetError(- f"Invalid preset catalog format from {url}: "- "'presets' must be a JSON object"- )-- def _load_catalog_config(self, config_path: Path) -> Optional[List[PresetCatalogEntry]]:- """Load catalog stack configuration from a YAML file.-- Args:- config_path: Path to preset-catalogs.yml-- Returns:- Ordered list of PresetCatalogEntry objects, or None if file- doesn't exist or contains no valid catalog entries.-- Raises:- PresetValidationError: If any catalog entry has an invalid URL,- the file cannot be parsed, or a priority value is invalid.- """- if not config_path.exists():- return None- try:- data = yaml.safe_load(config_path.read_text(encoding="utf-8"))- except (yaml.YAMLError, OSError, UnicodeError) as e:- raise PresetValidationError(- f"Failed to read catalog config {config_path}: {e}"- )- # Do NOT coerce with ``or {}`` here: that also turns a FALSY- # non-mapping top level (``[]``, ``false``, ``0``, ``''``) into ``{}``- # and silently swallows it, while a TRUTHY non-mapping (``5``, a bare- # list) correctly raises below. Only an empty document/explicit- # ``null`` means "no document".- if data is None:- return None- if not isinstance(data, dict):- raise PresetValidationError(- f"Invalid catalog config {config_path}: expected a mapping at root, got {type(data).__name__}"- )- # Same asymmetry one nesting level down: the shape check has to run- # BEFORE the emptiness check, or a FALSY non-list ``catalogs`` value- # (``{}``, ``''``, ``0``, ``false``) is silently swallowed as "no- # catalogs" while a TRUTHY non-list (``catalogs: "not-a-list"``)- # correctly raises. An absent key or an explicit ``catalogs: null``- # both keep their existing "nothing configured here" behavior.- catalogs_data = data.get("catalogs")- if catalogs_data is None:- return None- if not isinstance(catalogs_data, list):- raise PresetValidationError(- f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"- )- if not catalogs_data:- return None- entries: List[PresetCatalogEntry] = []- for idx, item in enumerate(catalogs_data):- if not isinstance(item, dict):- raise PresetValidationError(- f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"- )- url = str(item.get("url", "")).strip()- if not url:- continue- self._validate_catalog_url(url)- raw_priority = item.get("priority", idx + 1)- # Reject bools explicitly: ``bool`` is a subclass of ``int`` so- # ``int(True)`` silently returns 1, which would let a YAML- # ``priority: true`` slip through as a valid priority of 1. The- # sibling integration-catalog reader in ``catalogs.py`` already- # guards this; mirror the check here so the three catalog- # validators stay consistent.- if isinstance(raw_priority, bool):- raise PresetValidationError(- f"Invalid priority for catalog '{item.get('name', idx + 1)}': "- f"expected integer, got {raw_priority!r}"- )- try:- priority = int(raw_priority)- except (TypeError, ValueError, OverflowError):- # OverflowError: int(float("inf")) β a YAML ``priority: .inf``- # would otherwise escape as an uncaught traceback instead of the- # clean validation error (mirrors catalogs.py).- raise PresetValidationError(- f"Invalid priority for catalog '{item.get('name', idx + 1)}': "- f"expected integer, got {raw_priority!r}"- )- raw_install = item.get("install_allowed", False)- if isinstance(raw_install, str):- install_allowed = raw_install.strip().lower() in ("true", "yes", "1")- else:- install_allowed = bool(raw_install)- raw_name = item.get("name")- name = str(raw_name).strip() if raw_name is not None else ""- if not name:- name = f"catalog-{len(entries) + 1}"-- entries.append(PresetCatalogEntry(- url=url,- name=name,- priority=priority,- install_allowed=install_allowed,- description=str(item.get("description", "")),- ))- entries.sort(key=lambda e: e.priority)- return entries if entries else None-- def get_active_catalogs(self) -> List[PresetCatalogEntry]:- """Get the ordered list of active preset catalogs.-- Resolution order:- 1. SPECKIT_PRESET_CATALOG_URL env var β single catalog replacing all defaults- 2. Project-level .specify/preset-catalogs.yml- 3. User-level ~/.specify/preset-catalogs.yml- 4. Built-in default stack (default + community)-- Returns:- List of PresetCatalogEntry objects sorted by priority (ascending)-- Raises:- PresetValidationError: If a catalog URL is invalid- """- import sys-- # 1. SPECKIT_PRESET_CATALOG_URL env var replaces all defaults- if env_value := os.environ.get("SPECKIT_PRESET_CATALOG_URL"):- catalog_url = env_value.strip()- self._validate_catalog_url(catalog_url)- if catalog_url != self.DEFAULT_CATALOG_URL:- if not getattr(self, "_non_default_catalog_warning_shown", False):- print(- "Warning: Using non-default preset catalog. "- "Only use catalogs from sources you trust.",- file=sys.stderr,- )- self._non_default_catalog_warning_shown = True- return [PresetCatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_PRESET_CATALOG_URL")]-- # 2. Project-level config overrides all defaults- project_config_path = self.project_root / ".specify" / "preset-catalogs.yml"- catalogs = self._load_catalog_config(project_config_path)- if catalogs is not None:- return catalogs-- # 3. User-level config- user_config_path = Path.home() / ".specify" / "preset-catalogs.yml"- catalogs = self._load_catalog_config(user_config_path)- if catalogs is not None:- return catalogs-- # 4. Built-in default stack- return [- PresetCatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable presets"),- PresetCatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed presets (discovery only)"),- ]-- def get_catalog_url(self) -> str:- """Get the primary catalog URL.-- Returns the URL of the highest-priority catalog. Kept for backward- compatibility. Use get_active_catalogs() for full multi-catalog support.-- Returns:- URL of the primary catalog- """- active = self.get_active_catalogs()- return active[0].url if active else self.DEFAULT_CATALOG_URL-- def _get_cache_paths(self, url: str):- """Get cache file paths for a given catalog URL.-- For the DEFAULT_CATALOG_URL, uses legacy cache files for backward- compatibility. For all other URLs, uses URL-hash-based cache files.-- Returns:- Tuple of (cache_file_path, cache_metadata_path)- """- if url == self.DEFAULT_CATALOG_URL:- return self.cache_file, self.cache_metadata_file- url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]- return (- self.cache_dir / f"catalog-{url_hash}.json",- self.cache_dir / f"catalog-{url_hash}-metadata.json",- )-- def _is_url_cache_valid(self, url: str) -> bool:- """Check if cached catalog for a specific URL is still valid."""- cache_file, metadata_file = self._get_cache_paths(url)- if not cache_file.exists() or not metadata_file.exists():- return False- try:- metadata = json.loads(metadata_file.read_text(encoding="utf-8"))- cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))- if cached_at.tzinfo is None:- cached_at = cached_at.replace(tzinfo=timezone.utc)- age_seconds = (- datetime.now(timezone.utc) - cached_at- ).total_seconds()- return age_seconds < self.CACHE_DURATION- except (- json.JSONDecodeError,- OSError,- UnicodeError,- ValueError,- KeyError,- TypeError,- AttributeError,- ):- # Cache validity is best-effort: invalid/missing fields, an- # unreadable metadata file (permissions / disk), a wrongly- # encoded one (written by a tool using the system locale- # codec), or a metadata payload that parses to a non-mapping- # like ``[]`` or ``"oops"`` (so ``metadata.get(...)`` raises- # ``AttributeError``) all degrade to "cache invalid" so the- # caller falls through to a network refetch instead of- # crashing.- return False-- def _fetch_single_catalog(self, entry: PresetCatalogEntry, force_refresh: bool = False) -> Dict[str, Any]:- """Fetch a single catalog with per-URL caching.-- Args:- entry: PresetCatalogEntry describing the catalog to fetch- force_refresh: If True, bypass cache-- Returns:- Catalog data dictionary-- Raises:- PresetError: If catalog cannot be fetched- """- cache_file, metadata_file = self._get_cache_paths(entry.url)-- # Use cache if valid. A previously-cached payload must clear the- # same shape checks as a freshly-fetched one β otherwise a once-- # poisoned cache would re-crash on every invocation despite the- # cache being "valid" by age. If validation fails on the cached- # read, fall through to the network fetch path so the cache gets- # refreshed.- if not force_refresh and self._is_url_cache_valid(entry.url):- try:- cached_data = json.loads(cache_file.read_text(encoding="utf-8"))- self._validate_catalog_payload(cached_data, entry.url)- return cached_data- except (json.JSONDecodeError, OSError, UnicodeError, PresetError):- # Cache is best-effort: a JSON-decode failure, an OS-level- # read failure (permissions / disk / handle limit), or a- # text-encoding failure on a cache file written by an- # older client all fall through to the network fetch path.- # Only the network failure is surfaced to the caller.- pass-- try:- # Validate EVERY redirect hop (not just the terminal URL): an- # https -> http -> attacker-controlled-https chain would pass a- # final-URL-only check while the insecure intermediate hop lets a- # network attacker rewrite the next redirect. redirect_validator runs- # before each hop; the final geturl() check is retained as a- # belt-and-braces guard. Mirrors bundler/services/adapters.py.- def _validate_redirect(_old_url: str, new_url: str) -> None:- self._validate_catalog_url(new_url)-- with self._open_url(- entry.url, timeout=10, redirect_validator=_validate_redirect- ) as response:- final_url = response.geturl()- if final_url != entry.url:- self._validate_catalog_url(final_url)- catalog_data = json.loads(- read_response_limited(- response,- max_bytes=MAX_JSON_CATALOG_BYTES,- error_type=PresetError,- label=f"preset catalog {entry.url}",- )- )-- self._validate_catalog_payload(catalog_data, entry.url)-- # Both files are written explicitly as UTF-8 to match the- # ``read_text(encoding="utf-8")`` on the read side and the- # ``integrations/catalog.py`` precedent. Without this,- # platforms whose default encoding isn't UTF-8 would write- # locale-encoded bytes the read path can't decode, forcing an- # unnecessary refetch on every invocation. The write itself- # is best-effort like the read side: an unwritable cache dir- # (read-only checkout, permissions) must not be re-raised as- # a ``PresetError`` for a payload that was already fetched- # and validated.- try:- self.cache_dir.mkdir(parents=True, exist_ok=True)- cache_file.write_text(- json.dumps(catalog_data, indent=2), encoding="utf-8"- )- metadata = {- "cached_at": datetime.now(timezone.utc).isoformat(),- "catalog_url": entry.url,- }- metadata_file.write_text(- json.dumps(metadata, indent=2), encoding="utf-8"- )- except OSError:- pass # Cache is best-effort; proceed with fetched data-- return catalog_data-- except (ImportError, Exception) as e:- if isinstance(e, PresetError):- raise- raise PresetError(- f"Failed to fetch preset catalog from {entry.url}: {e}"- )-- def _get_merged_packs(self, force_refresh: bool = False) -> Dict[str, Dict[str, Any]]:- """Fetch and merge presets from all active catalogs.-- Higher-priority catalogs (lower priority number) win on ID conflicts.-- Returns:- Merged dictionary of pack_id -> pack_data- """- active_catalogs = self.get_active_catalogs()- merged: Dict[str, Dict[str, Any]] = {}-- for entry in reversed(active_catalogs):- try:- data = self._fetch_single_catalog(entry, force_refresh)- for pack_id, pack_data in data.get("presets", {}).items():- # Per-entry guard: ``_fetch_single_catalog`` already- # validates that ``data["presets"]`` is a mapping, but it- # does not (and should not) validate every entry shape- # there β one malformed entry shouldn't poison an- # otherwise valid catalog. Skip non-mapping entries here- # so a payload like ``{"presets": {"foo": [], "bar":- # {...}}}`` still merges the valid entries without- # crashing on ``**pack_data``. Mirrors- # ``integrations/catalog.py:245``.- if not isinstance(pack_data, dict):- continue- pack_data_with_catalog = {**pack_data, "_catalog_name": entry.name, "_install_allowed": entry.install_allowed}- merged[pack_id] = pack_data_with_catalog- except PresetError:- continue-- return merged-- def is_cache_valid(self) -> bool:- """Check if cached catalog is still valid.-- Returns ``False`` for any read/decoding failure on the metadata- file (missing fields, malformed JSON, permissions / disk errors,- wrong text encoding) so callers fall through to a network refetch- instead of crashing. Treating cache validity as best-effort- matches the contract used by ``_is_url_cache_valid`` above.-- Returns:- True if cache exists and is within cache duration- """- if not self.cache_file.exists() or not self.cache_metadata_file.exists():- return False-- try:- metadata = json.loads(- self.cache_metadata_file.read_text(encoding="utf-8")- )- cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))- if cached_at.tzinfo is None:- cached_at = cached_at.replace(tzinfo=timezone.utc)- age_seconds = (- datetime.now(timezone.utc) - cached_at- ).total_seconds()- return age_seconds < self.CACHE_DURATION- except (- json.JSONDecodeError,- OSError,- UnicodeError,- ValueError,- KeyError,- TypeError,- AttributeError,- ):- # ``AttributeError`` covers the case where the metadata file- # parses to a non-mapping (``[]``, ``"oops"``, ``42``) so- # ``metadata.get(...)`` would otherwise crash. All decode /- # shape failures degrade to "cache invalid" so the caller- # falls through to a network refetch.- return False-- def fetch_catalog(self, force_refresh: bool = False) -> Dict[str, Any]:- """Fetch preset catalog from URL or cache.-- Args:- force_refresh: If True, bypass cache and fetch from network-- Returns:- Catalog data dictionary-- Raises:- PresetError: If catalog cannot be fetched- """- catalog_url = self.get_catalog_url()-- # Match the ``_fetch_single_catalog`` cache contract: a poisoned- # or unreadable cache silently falls through to a network refetch- # rather than crashing the caller. ``_validate_catalog_payload``- # is reused here so a cache written by an older client- # (pre-validation) is rejected and refreshed instead of returning- # the stale malformed payload.- if not force_refresh and self.is_cache_valid():- try:- metadata = json.loads(- self.cache_metadata_file.read_text(encoding="utf-8")- )- if metadata.get("catalog_url") == catalog_url:- cached_data = json.loads(- self.cache_file.read_text(encoding="utf-8")- )- self._validate_catalog_payload(cached_data, catalog_url)- return cached_data- except (json.JSONDecodeError, OSError, UnicodeError, PresetError):- # Cache is corrupt, unreadable, or fails the shape check;- # fall through to network fetch.- pass-- try:- # Same redirect hardening as _fetch_single_catalog: validate every- # redirect hop AND the final URL so this legacy single-catalog path- # is not vulnerable to an HTTPS->HTTP redirected payload either.- def _validate_redirect(_old_url: str, new_url: str) -> None:- self._validate_catalog_url(new_url)-- with self._open_url(- catalog_url, timeout=10, redirect_validator=_validate_redirect- ) as response:- final_url = response.geturl()- if final_url != catalog_url:- self._validate_catalog_url(final_url)- catalog_data = json.loads(- read_response_limited(- response,- max_bytes=MAX_JSON_CATALOG_BYTES,- error_type=PresetError,- label=f"preset catalog {catalog_url}",- )- )-- # Validate catalog structure. Reuses the same helper as- # ``_fetch_single_catalog`` so all three branches (root type,- # missing keys, nested-mapping type) stay consistent.- self._validate_catalog_payload(catalog_data, catalog_url)-- # Save to cache. Explicit UTF-8 on both writes mirrors the- # ``read_text(encoding="utf-8")`` on the read side and the- # ``integrations/catalog.py`` precedent β otherwise platforms- # whose default encoding isn't UTF-8 would write- # locale-encoded bytes the read path can't decode, forcing an- # unnecessary refetch on every invocation. Like the read- # side, the write is best-effort: an unwritable cache dir- # must not be re-raised as a ``PresetError`` for a payload- # that was already fetched and validated.- try:- self.cache_dir.mkdir(parents=True, exist_ok=True)- self.cache_file.write_text(- json.dumps(catalog_data, indent=2), encoding="utf-8"- )-- metadata = {- "cached_at": datetime.now(timezone.utc).isoformat(),- "catalog_url": catalog_url,- }- self.cache_metadata_file.write_text(- json.dumps(metadata, indent=2), encoding="utf-8"- )- except OSError:- pass # Cache is best-effort; proceed with fetched data-- return catalog_data-- except (ImportError, Exception) as e:- if isinstance(e, PresetError):- raise- raise PresetError(- f"Failed to fetch preset catalog from {catalog_url}: {e}"- )-- def search(- self,- query: Optional[str] = None,- tag: Optional[str] = None,- author: Optional[str] = None,- ) -> List[Dict[str, Any]]:- """Search catalog for presets.-- Searches across all active catalogs (merged by priority) so that- community and custom catalogs are included in results.-- Args:- query: Search query (searches name, description, tags)- tag: Filter by specific tag- author: Filter by author name-- Returns:- List of matching preset metadata- """- try:- packs = self._get_merged_packs()- except PresetError:- return []-- results = []-- for pack_id, pack_data in packs.items():- if author:- author_val = pack_data.get("author", "")- if not isinstance(author_val, str):- author_val = str(author_val) if author_val is not None else ""- if author_val.lower() != author.lower():- continue-- if tag:- raw_tags = pack_data.get("tags", [])- tags_list = raw_tags if isinstance(raw_tags, list) else []- if tag.lower() not in [- str(t).lower() for t in tags_list- ]:- continue-- if query:- query_lower = query.lower()- raw_tags = pack_data.get("tags", [])- tags_list = raw_tags if isinstance(raw_tags, list) else []- name_val = pack_data.get("name", "")- desc_val = pack_data.get("description", "")- searchable_text = " ".join(- [- str(name_val) if name_val is not None else "",- str(desc_val) if desc_val is not None else "",- pack_id,- ]- + [str(t) for t in tags_list]- ).lower()-- if query_lower not in searchable_text:- continue-- results.append({**pack_data, "id": pack_id})-- return results-- def get_pack_info(- self, pack_id: str- ) -> Optional[Dict[str, Any]]:- """Get detailed information about a specific preset.-- Searches across all active catalogs (merged by priority).-- Args:- pack_id: ID of the preset-- Returns:- Pack metadata or None if not found- """- try:- packs = self._get_merged_packs()- except PresetError:- return None-- if pack_id in packs:- return {**packs[pack_id], "id": pack_id}- return None-- def download_pack(- self, pack_id: str, target_dir: Optional[Path] = None- ) -> Path:- """Download a preset archive from a catalog.-- Args:- pack_id: ID of the preset to download- target_dir: Directory to save the archive-- Returns:- Path to the downloaded archive-- Raises:- PresetError: If pack not found or download fails- """- import urllib.error-- pack_info = self.get_pack_info(pack_id)- if not pack_info:- raise PresetError(- f"Preset '{pack_id}' not found in catalog"- )-- # Bundled presets without a download URL must be installed locally- if pack_info.get("bundled") and not pack_info.get("download_url"):- from ..extensions import REINSTALL_COMMAND- raise PresetError(- f"Preset '{pack_id}' is bundled with spec-kit and has no download URL. "- f"It should be installed from the local package. "- f"Use 'specify preset add {pack_id}' to install from the bundled package, "- f"or reinstall spec-kit if the bundled files are missing: {REINSTALL_COMMAND}"- )-- if not pack_info.get("_install_allowed", True):- catalog_name = pack_info.get("_catalog_name", "unknown")- raise PresetError(- f"Preset '{pack_id}' is from the '{catalog_name}' catalog which does not allow installation. "- f"Use --from with the preset's repository URL instead."- )-- download_url = pack_info.get("download_url")- if not download_url:- raise PresetError(- f"Preset '{pack_id}' has no download URL"- )- if not isinstance(download_url, str):- raise PresetError(- f"Preset download URL is malformed: {download_url}"- )-- from urllib.parse import urlparse-- # A malformed authority (e.g. an unterminated IPv6 bracket- # "https://[::1") makes urlparse / hostname access raise ValueError.- # The download_url comes from catalog payload data, so surface a clean- # PresetError rather than leaking a raw ValueError past the command- # handler (which only catches PresetError). Mirrors catalogs (#3435)- # and workflows/catalog.py (#3484).- try:- parsed = urlparse(download_url)- hostname = parsed.hostname- parsed.port- except ValueError:- raise PresetError(- f"Preset download URL is malformed: {download_url}"- ) from None- if not hostname:- raise PresetError(- f"Preset download URL is malformed: {download_url}"- )- if not is_https_or_localhost_http(download_url):- raise PresetError(- f"Preset download URL must use HTTPS: {download_url}"- )-- if target_dir is None:- target_dir = self.cache_dir / "downloads"- target_dir = Path(target_dir)- version = pack_info.get("version", "unknown")- declared_format = archive_format_from_name(download_url)- build_safe_download_path(- target_dir,- pack_id,- version,- error_type=PresetError,- label="preset",- suffix=archive_suffix(declared_format or "tar.gz"),- )- target_dir.mkdir(parents=True, exist_ok=True)-- original_download_url = download_url- extra_headers = None- resolved_download_url = self._resolve_github_release_asset_api_url(download_url)- if resolved_download_url:- download_url = resolved_download_url- extra_headers = {"Accept": "application/octet-stream"}-- staging_path: Path | None = None- try:- with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:- archive_data = read_response_limited(- response,- error_type=PresetError,- label=f"preset '{pack_id}' download",- )- final_url = (- response.geturl()- if hasattr(response, "geturl")- else download_url- )- content_type = (- response.getheader("Content-Type")- if hasattr(response, "getheader")- else None- )-- verify_archive_sha256(- archive_data, pack_info.get("sha256"), pack_id, PresetError- )-- with tempfile.NamedTemporaryFile(- prefix="preset-download-",- suffix=".archive",- dir=target_dir,- delete=False,- ) as staging_file:- staging_path = Path(staging_file.name)- staging_file.write(archive_data)- archive_format = detect_archive_format(- staging_path,- source_name=(- final_url- if archive_format_from_name(final_url) is not None- else original_download_url- ),- content_type=content_type,- error_type=PresetError,- )- archive_path = build_safe_download_path(- target_dir,- pack_id,- version,- error_type=PresetError,- label="preset",- suffix=archive_suffix(archive_format),- )- os.replace(staging_path, archive_path)- staging_path = None- return archive_path-- except urllib.error.URLError as e:- raise PresetError(- f"Failed to download preset from {download_url}: {e}"- )- except IOError as e:- raise PresetError(f"Failed to save preset archive: {e}")- finally:- if staging_path is not None:- staging_path.unlink(missing_ok=True)-- def clear_cache(self):- """Clear all catalog cache files, including per-URL hashed caches."""- if self.cache_dir.exists():- for f in self.cache_dir.iterdir():- if f.is_file() and f.name.startswith("catalog"):- f.unlink(missing_ok=True)---class PresetResolver:- """Resolves template names to file paths using a priority stack.-- Resolution order:- 1. .specify/templates/overrides/ - Project-local overrides- 2. .specify/presets/<preset-id>/ - Installed presets- 3. .specify/extensions/<ext-id>/templates/ - Extension-provided templates- 4. .specify/templates/ - Core templates (shipped with Spec Kit)- """-- def __init__(self, project_root: Path):- """Initialize preset resolver.-- Args:- project_root: Path to project root directory- """- self.project_root = project_root- self.templates_dir = project_root / ".specify" / "templates"- self.presets_dir = project_root / ".specify" / "presets"- self.overrides_dir = self.templates_dir / "overrides"- self.extensions_dir = project_root / ".specify" / "extensions"- self._manifest_cache: Dict[str, Optional["PresetManifest"]] = {}-- def _get_manifest(self, pack_dir: Path) -> Optional["PresetManifest"]:- """Get a cached preset manifest, parsing it on first access."""- key = str(pack_dir)- if key not in self._manifest_cache:- manifest_path = pack_dir / "preset.yml"- if manifest_path.exists():- try:- self._manifest_cache[key] = PresetManifest(manifest_path)- except PresetValidationError:- self._manifest_cache[key] = None- else:- self._manifest_cache[key] = None- return self._manifest_cache[key]-- @staticmethod- def _is_safe_registry_id(value: object) -> bool:- return isinstance(value, str) and re.fullmatch(r"[a-z0-9-]+", value) is not None-- def _get_all_presets_by_priority(self) -> List[tuple[str, dict]]:- registry = PresetRegistry(self.presets_dir)- return [- (pack_id, metadata)- for pack_id, metadata in registry.list_by_priority()- if self._is_safe_registry_id(pack_id)- ]-- def _manifest_declared_template(- self, pack_dir: Path, template_name: str, template_type: str- ) -> tuple[dict | None, Path | None]:- """Resolve a preset's manifest-declared template entry and usable file.-- Returns ``(entry, candidate)``:- - ``entry`` is the matching ``provides.templates`` mapping, or ``None`` if- the manifest is absent or does not list this ``(name, type)``.- - ``candidate`` is the declared ``file:`` resolved under ``pack_dir`` IFF- it is a regular file (``is_file()``); ``None`` otherwise β a missing,- empty, or non-file (e.g. directory) declaration yields ``(entry, None)``.-- The manifest is authoritative: when it declares a template (``entry`` is- not ``None``) but the file is unusable (``candidate`` is ``None``),- callers must NOT fall back to the convention lookup β that would mask a- typo or pick up an undeclared file. Shared by ``resolve()`` and- ``collect_all_layers()`` so their manifest-first resolution cannot- silently diverge again (the divergence this fix addressed).- """- manifest = self._get_manifest(pack_dir)- if not manifest:- return None, None- for tmpl in manifest.templates:- if tmpl.get("name") == template_name and tmpl.get("type") == template_type:- file_path = tmpl.get("file")- if file_path:- manifest_candidate = pack_dir / file_path- return tmpl, (- manifest_candidate if manifest_candidate.is_file() else None- )- return tmpl, None- return None, None-- def _extension_manifest_declared_template(- self, ext_dir: Path, template_name: str, template_type: str- ) -> tuple[dict | None, Path | None]:- """Resolve an extension's manifest-declared command/template/script entry and usable file.-- Mirrors ``_manifest_declared_template`` (for presets): returns ``(entry, candidate)``- where ``entry`` is the matching ``provides.<type>`` mapping, or ``None`` if the- extension has no (valid) manifest or doesn't declare this ``(name, type)``.- ``candidate`` is the declared ``file:`` resolved under ``ext_dir`` IFF it is a- regular file that stays within ``ext_dir`` (guards against path traversal via a- malformed manifest, mirroring ``resolve_extension_command_via_manifest``);- ``None`` otherwise.-- The manifest is authoritative: when ``entry`` is not ``None`` but ``candidate`` is- ``None``, callers must NOT fall back to convention-based lookup β that would mask- a typo or pick up an undeclared file. Shared by ``resolve()`` and- ``collect_all_layers()`` so their manifest-first resolution cannot silently- diverge (the divergence flagged in review on #4012).- """- if template_type not in ("command", "template", "script"):- return None, None- ext_manifest_path = ext_dir / "extension.yml"- if not ext_manifest_path.exists():- return None, None- from ..extensions import ExtensionManifest, ValidationError as ExtValidationError-- try:- ext_manifest = ExtensionManifest(ext_manifest_path)- except (ExtValidationError, yaml.YAMLError, OSError, TypeError, AttributeError):- return None, None- if template_type == "command":- entries = ext_manifest.commands- elif template_type == "template":- entries = ext_manifest.templates- else:- entries = ext_manifest.scripts- for entry in entries:- if entry.get("name") != template_name:- continue- file_rel = entry.get("file")- if not file_rel:- return entry, None- rel_path = Path(file_rel)- if rel_path.is_absolute():- return entry, None- candidate = ext_dir / rel_path- try:- # Resolve only for the containment check, not for the- # returned path -- resolving the returned path would follow- # symlinks in ext_dir's ancestors (e.g. a symlinked tmp dir- # on macOS) and diverge from the unresolved paths convention- # lookup returns for the same directory.- candidate.resolve().relative_to(ext_dir.resolve()) # raises ValueError if outside- except (OSError, ValueError):- return entry, None- return entry, (candidate if candidate.is_file() else None)- return None, None-- def _get_all_extensions_by_priority(self) -> list[tuple[int, str, dict | None]]:- """Build unified list of registered and unregistered extensions sorted by priority.-- Registered extensions use their stored priority; unregistered directories- get implicit priority=10. Results are sorted by (priority, ext_id) for- deterministic ordering.-- Returns:- List of (priority, ext_id, metadata_or_none) tuples sorted by priority.- """- if not self.extensions_dir.exists():- return []-- registry = ExtensionRegistry(self.extensions_dir)- # Fail closed on a corrupt registry. ExtensionRegistry._load() recovers- # by normalizing an unreadable registry to an empty mapping, which would- # otherwise cause the directory scan below to admit every on-disk- # directory as an unregistered, enabled extension β a fail-open path- # that could supply constitution content from an invalid registry state.- if registry.is_corrupt():- raise PresetValidationError(- f"Invalid extension registry {registry.registry_path}: "- "refusing to enumerate extensions"- )- # Use keys() to track ALL extensions (including corrupted entries) without deep copy- # This prevents corrupted entries from being picked up as "unregistered" dirs- registered_extension_ids = registry.keys()-- # Get all registered extensions including disabled; we filter disabled manually below- all_registered = registry.list_by_priority(include_disabled=True)-- all_extensions: list[tuple[int, str, dict | None]] = []-- # Only include enabled extensions in the result- for ext_id, metadata in all_registered:- if not self._is_safe_registry_id(ext_id):- continue- # Skip disabled extensions- if not metadata.get("enabled", True):- continue- priority = normalize_priority(metadata.get("priority") if metadata else None)- all_extensions.append((priority, ext_id, metadata))-- # Add unregistered directories with implicit priority=10- for ext_dir in self.extensions_dir.iterdir():- if not ext_dir.is_dir() or not self._is_safe_registry_id(ext_dir.name):- continue- if ext_dir.name not in registered_extension_ids:- all_extensions.append((10, ext_dir.name, None))-- # Sort by (priority, ext_id) for deterministic ordering- all_extensions.sort(key=lambda x: (x[0], x[1]))- return all_extensions-- @staticmethod- def _core_stem(template_name: str) -> Optional[str]:- """Extract the stem for core command lookup.-- Commands use dot notation (e.g. ``speckit.specify``), but core- command files are named by stem (e.g. ``specify.md``). Returns- the stem if *template_name* follows the ``speckit.<stem>`` pattern,- or ``None`` otherwise.- """- if template_name.startswith("speckit."):- return template_name[len("speckit."):]- return None-- def resolve(- self,- template_name: str,- template_type: str = "template",- skip_presets: bool = False,- ) -> Optional[Path]:- """Resolve a template name to its file path.-- Walks the priority stack and returns the first match.-- Args:- template_name: Template name (e.g., "spec-template")- template_type: Template type ("template", "command", or "script")- skip_presets: When True, skip tier 2 (installed presets). Use- resolve_core() as the preferred caller-facing API for this.-- Returns:- Path to the resolved template file, or None if not found- """- # Determine subdirectory based on template type- if template_type == "template":- subdirs = ["templates", ""]- elif template_type == "command":- subdirs = ["commands"]- elif template_type == "script":- subdirs = ["scripts"]- else:- subdirs = [""]-- # Determine file extension based on template type- ext = ".md"- if template_type == "script":- ext = ".sh" # scripts use .sh; callers can also check .ps1-- # Priority 1: Project-local overrides- if template_type == "script":- override = self.overrides_dir / "scripts" / f"{template_name}{ext}"- else:- override = self.overrides_dir / f"{template_name}{ext}"- if override.exists():- return override-- # Priority 2: Installed presets (sorted by priority β lower number wins)- if not skip_presets and self.presets_dir.exists():- for pack_id, _metadata in self._get_all_presets_by_priority():- pack_dir = self.presets_dir / pack_id- # The preset manifest is authoritative: if it declares this- # template with an explicit ``file:``, resolve to that path β- # and do NOT fall back to convention when it's missing, to- # avoid masking typos or picking up an undeclared file. Only- # when the manifest is absent or doesn't list this template do- # we use the convention-based subdir lookup. Mirrors- # collect_all_layers()/resolve_content() so resolve() and- # resolve_with_source() agree with them instead of returning- # the core template (or a stray convention file).- entry, manifest_candidate = self._manifest_declared_template(- pack_dir, template_name, template_type- )- if manifest_candidate is not None:- return manifest_candidate- if entry is not None:- # Manifest declares this template but the file is missing,- # non-file (e.g. a directory), or an empty/falsey ``file``- # value. The manifest is authoritative, so skip this pack's- # convention fallback rather than mask a typo β mirrors- # collect_all_layers().- continue- for subdir in subdirs:- if subdir:- candidate = pack_dir / subdir / f"{template_name}{ext}"- else:- candidate = pack_dir / f"{template_name}{ext}"- if candidate.exists():- return candidate-- # Priority 3: Extension-provided templates (sorted by priority β lower number wins)- for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():- ext_dir = self.extensions_dir / ext_id- if not ext_dir.is_dir():- continue- # The extension manifest is authoritative, same as preset manifests- # above: check it before convention-based lookup so a declared entry- # at a non-conventional path wins over a stale conventional file.- entry, manifest_candidate = self._extension_manifest_declared_template(- ext_dir, template_name, template_type- )- if manifest_candidate is not None:- return manifest_candidate- if entry is not None:- continue- for subdir in subdirs:- if subdir:- candidate = ext_dir / subdir / f"{template_name}{ext}"- else:- candidate = ext_dir / f"{template_name}{ext}"- if candidate.exists():- return candidate-- # Priority 4: Core templates- if template_type == "template":- core = self.templates_dir / f"{template_name}.md"- if core.exists():- return core- elif template_type == "command":- core = self.templates_dir / "commands" / f"{template_name}.md"- if core.exists():- return core- # Fallback: speckit.<stem> β <stem>.md- stem = self._core_stem(template_name)- if stem:- core = self.templates_dir / "commands" / f"{stem}.md"- if core.exists():- return core- elif template_type == "script":- core = self.templates_dir / "scripts" / f"{template_name}{ext}"- if core.exists():- return core-- # Priority 5: Bundled core_pack (wheel install) or repo-root templates- # (source-checkout / editable install). This is the canonical home for- # speckit's built-in command/template files and must always be checked- # so that strategy:wrap presets can locate {CORE_TEMPLATE}.- from specify_cli import _locate_core_pack, _repo_root # local import to avoid cycles- _core_pack = _locate_core_pack()- if _core_pack is not None:- # Wheel install path- if template_type == "template":- candidate = _core_pack / "templates" / f"{template_name}.md"- elif template_type == "command":- candidate = _core_pack / "commands" / f"{template_name}.md"- if not candidate.exists():- stem = self._core_stem(template_name)- if stem:- candidate = _core_pack / "commands" / f"{stem}.md"- elif template_type == "script":- candidate = _core_pack / "scripts" / f"{template_name}{ext}"- else:- candidate = _core_pack / f"{template_name}.md"- if candidate.exists():- return candidate- else:- # Source-checkout / editable install: templates live at repo root- repo_root = _repo_root()- if template_type == "template":- candidate = repo_root / "templates" / f"{template_name}.md"- elif template_type == "command":- candidate = repo_root / "templates" / "commands" / f"{template_name}.md"- if not candidate.exists():- stem = self._core_stem(template_name)- if stem:- candidate = repo_root / "templates" / "commands" / f"{stem}.md"- elif template_type == "script":- candidate = repo_root / "scripts" / f"{template_name}{ext}"- else:- candidate = repo_root / f"{template_name}.md"- if candidate.exists():- return candidate-- return None-- def resolve_core(- self,- template_name: str,- template_type: str = "template",- ) -> Optional[Path]:- """Resolve while skipping installed presets (tier 2).-- Searches tiers 1, 3, 4, and 5 (bundled core_pack / repo-root fallback).- Use when resolving {CORE_TEMPLATE} to guarantee the result is actual- base content, never another preset's wrap output.- """- return self.resolve(template_name, template_type, skip_presets=True)-- def resolve_extension_command_via_manifest(self, cmd_name: str) -> Optional[Path]:- """Resolve an extension command by consulting installed extension manifests.-- Walks installed extension directories in priority order, loads each- extension.yml via ExtensionManifest, and looks up the command by its- declared name to find the actual file path. This is necessary because- the manifest's ``provides.commands[].file`` field is authoritative and- may differ from the command name- (e.g. ``speckit.selftest.extension`` β ``commands/selftest.md``).-- Returns None if no manifest maps the given command name, so the caller- can fall back to the name-based lookup.- """- if not self.extensions_dir.exists():- return None-- from ..extensions import ExtensionManifest, ValidationError-- for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():- ext_dir = self.extensions_dir / ext_id- manifest_path = ext_dir / "extension.yml"- if not manifest_path.is_file():- continue- try:- manifest = ExtensionManifest(manifest_path)- except (ValidationError, OSError, TypeError, AttributeError):- continue- for cmd_info in manifest.commands:- if cmd_info.get("name") != cmd_name:- continue- file_rel = cmd_info.get("file")- if not file_rel:- continue- # Mirror the containment check in ExtensionManager to guard against- # path traversal via a malformed manifest (e.g. file: ../../AGENTS.md).- cmd_path = Path(file_rel)- if cmd_path.is_absolute():- continue- try:- ext_root = ext_dir.resolve()- candidate = (ext_root / cmd_path).resolve()- candidate.relative_to(ext_root) # raises ValueError if outside- except (OSError, ValueError):- continue- if candidate.is_file():- return candidate- return None-- def resolve_with_source(- self,- template_name: str,- template_type: str = "template",- ) -> Optional[Dict[str, str]]:- """Resolve a template name and return source attribution.-- Args:- template_name: Template name (e.g., "spec-template")- template_type: Template type ("template", "command", or "script")-- Returns:- Dictionary with 'path' and 'source' keys, or None if not found- """- # Delegate to resolve() for the actual lookup, then determine source- resolved = self.resolve(template_name, template_type)- if resolved is None:- return None-- resolved_str = str(resolved)-- # Determine source attribution- if str(self.overrides_dir) in resolved_str:- return {"path": resolved_str, "source": "project override"}-- if str(self.presets_dir) in resolved_str and self.presets_dir.exists():- for pack_id, metadata in self._get_all_presets_by_priority():- pack_dir = self.presets_dir / pack_id- try:- resolved.relative_to(pack_dir)- version = metadata.get("version", "?")- return {- "path": resolved_str,- "source": f"{pack_id} v{version}",- }- except ValueError:- continue-- for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():- ext_dir = self.extensions_dir / ext_id- if not ext_dir.is_dir():- continue- try:- resolved.relative_to(ext_dir)- if ext_meta:- version = ext_meta.get("version", "?")- return {- "path": resolved_str,- "source": f"extension:{ext_id} v{version}",- }- else:- return {- "path": resolved_str,- "source": f"extension:{ext_id} (unregistered)",- }- except ValueError:- continue-- return {"path": resolved_str, "source": "core"}-- def collect_all_layers(- self,- template_name: str,- template_type: str = "template",- ) -> List[Dict[str, Any]]:- """Collect all layers in the priority stack for a template.-- Returns layers from highest priority (checked first) to lowest priority.- Each layer is a dict with 'path', 'source', and 'strategy' keys.-- Args:- template_name: Template name (e.g., "spec-template")- template_type: Template type ("template", "command", or "script")-- Returns:- List of layer dicts ordered highest-to-lowest priority.- """- if template_type == "template":- subdirs = ["templates", ""]- elif template_type == "command":- subdirs = ["commands"]- elif template_type == "script":- subdirs = ["scripts"]- else:- subdirs = [""]-- ext = ".md"- if template_type == "script":- ext = ".sh"-- layers: List[Dict[str, Any]] = []-- def _find_in_subdirs(base_dir: Path) -> Optional[Path]:- for subdir in subdirs:- if subdir:- candidate = base_dir / subdir / f"{template_name}{ext}"- else:- candidate = base_dir / f"{template_name}{ext}"- if candidate.exists():- return candidate- return None-- # Priority 1: Project-local overrides (always "replace" strategy)- if template_type == "script":- override = self.overrides_dir / "scripts" / f"{template_name}{ext}"- else:- override = self.overrides_dir / f"{template_name}{ext}"- if override.exists():- layers.append({- "path": override,- "source": "project override",- "strategy": "replace",- })-- # Priority 2: Installed presets (sorted by priority β lower number = higher precedence)- if self.presets_dir.exists():- for pack_id, metadata in self._get_all_presets_by_priority():- pack_dir = self.presets_dir / pack_id- # Read strategy and manifest file path from preset manifest- strategy = "replace"- manifest_has_strategy = False- entry, manifest_candidate = self._manifest_declared_template(- pack_dir, template_name, template_type- )- if entry is not None:- strategy = entry.get("strategy", "replace")- manifest_has_strategy = "strategy" in entry- # Use the manifest's declared file when it's a usable regular file;- # only fall back to convention-based lookup when the manifest- # doesn't list this template at all, so preset.yml stays- # authoritative (a declared-but-unusable file skips convention β- # parity with resolve()).- candidate = None- if manifest_candidate is not None:- candidate = manifest_candidate- elif entry is None:- candidate = _find_in_subdirs(pack_dir)- if candidate:- # Legacy fallback: if manifest doesn't explicitly declare a- # strategy, check the command file's frontmatter for any valid- # strategy. Skip when the manifest entry includes strategy key- # (even if it's "replace") to avoid overriding explicit declarations.- if not manifest_has_strategy and strategy == "replace" and template_type == "command":- try:- cmd_content = candidate.read_text(encoding="utf-8")- lines = cmd_content.splitlines(keepends=True)- if lines and lines[0].rstrip("\r\n") == "---":- fence_end = -1- for fi, fline in enumerate(lines[1:], start=1):- if fline.rstrip("\r\n") == "---":- fence_end = fi- break- if fence_end > 0:- fm_text = "".join(lines[1:fence_end])- fm_data = yaml.safe_load(fm_text)- if isinstance(fm_data, dict):- fm_strategy = fm_data.get("strategy")- if isinstance(fm_strategy, str) and fm_strategy.lower() in VALID_PRESET_STRATEGIES:- strategy = fm_strategy.lower()- except (UnicodeDecodeError, yaml.YAMLError, OSError):- # Best-effort legacy frontmatter parsing: keep default- # strategy ("replace") when content is unreadable/invalid.- pass- version = metadata.get("version", "?") if metadata else "?"- layers.append({- "path": candidate,- "source": f"{pack_id} v{version}",- "strategy": strategy,- })-- # Priority 3: Extension-provided templates (always "replace")- for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():- ext_dir = self.extensions_dir / ext_id- if not ext_dir.is_dir():- continue- # The extension manifest is authoritative, same as preset manifests- # above: check it before convention-based lookup so a declared entry- # at a non-conventional path wins over a stale conventional file, and- # a declared-but-missing file isn't silently masked by convention.- entry, candidate = self._extension_manifest_declared_template(- ext_dir, template_name, template_type- )- if entry is None:- candidate = _find_in_subdirs(ext_dir)- if candidate:- if ext_meta:- version = ext_meta.get("version", "?")- source = f"extension:{ext_id} v{version}"- else:- source = f"extension:{ext_id} (unregistered)"- layers.append({- "path": candidate,- "source": source,- "strategy": "replace",- "extension_id": ext_id,- "extension_dir": ext_dir,- })-- # Priority 4: Core templates (always "replace")- core = None- if template_type == "template":- c = self.templates_dir / f"{template_name}.md"- if c.exists():- core = c- elif template_type == "command":- c = self.templates_dir / "commands" / f"{template_name}.md"- if c.exists():- core = c- else:- # Fallback: speckit.<stem> β <stem>.md- stem = self._core_stem(template_name)- if stem:- c = self.templates_dir / "commands" / f"{stem}.md"- if c.exists():- core = c- elif template_type == "script":- c = self.templates_dir / "scripts" / f"{template_name}{ext}"- if c.exists():- core = c- if core:- layers.append({- "path": core,- "source": "core",- "strategy": "replace",- })- else:- # Priority 5: Bundled core_pack (wheel install) or repo-root- # templates (source-checkout), matching resolve()'s tier-5 fallback.- bundled = self._find_bundled_core(template_name, template_type, ext)- if bundled:- layers.append({- "path": bundled,- "source": "core (bundled)",- "strategy": "replace",- })-- return layers-- def _find_bundled_core(- self,- template_name: str,- template_type: str,- ext: str,- ) -> Optional[Path]:- """Find a core template from the bundled pack or source checkout.-- Mirrors the tier-5 fallback logic in ``resolve()`` so that- ``collect_all_layers()`` can locate base layers even when- ``.specify/templates/`` doesn't contain the core file.- """- try:- from specify_cli import _locate_core_pack, _repo_root- except ImportError:- return None-- stem = self._core_stem(template_name)- names = [template_name]- if stem and stem != template_name:- names.append(stem)-- core_pack = _locate_core_pack()- if core_pack is not None:- for name in names:- if template_type == "template":- c = core_pack / "templates" / f"{name}.md"- elif template_type == "command":- c = core_pack / "commands" / f"{name}.md"- elif template_type == "script":- c = core_pack / "scripts" / f"{name}{ext}"- else:- c = core_pack / f"{name}.md"- if c.exists():- return c- else:- repo_root = _repo_root()- for name in names:- if template_type == "template":- c = repo_root / "templates" / f"{name}.md"- elif template_type == "command":- c = repo_root / "templates" / "commands" / f"{name}.md"- elif template_type == "script":- c = repo_root / "scripts" / f"{name}{ext}"- else:- c = repo_root / f"{name}.md"- if c.exists():- return c- return None-- def resolve_content(- self,- template_name: str,- template_type: str = "template",- ) -> Optional[str]:- """Resolve a template name and return composed content.-- Walks the priority stack and composes content using strategies:- - replace (default): highest-priority content wins entirely- - prepend: content is placed before lower-priority content- - append: content is placed after lower-priority content- - wrap: content contains {CORE_TEMPLATE} placeholder replaced- with lower-priority content (or $CORE_SCRIPT for scripts)-- Composition is recursive β multiple composing presets chain.-- Args:- template_name: Template name (e.g., "spec-template")- template_type: Template type ("template", "command", or "script")-- Returns:- Composed content string, or None if not found- """- layers = self.collect_all_layers(template_name, template_type)- if not layers:- return None-- def _read_layer_content(layer: Dict[str, Any]) -> Optional[str]:- """Read a layer's raw text, rewriting extension-relative subdir- references (agents/, knowledge-base/, etc.) to their installed- location when the layer is extension-provided (#2101).-- Extension layers are always inserted with strategy "replace"- (see collect_all_layers), so a layer only ever needs this- rewrite when it wins outright above or serves as the- composition base below β never as a mid-stack composing- (append/prepend/wrap) layer.-- Returns None when the layer cannot be read or decoded:- collect_all_layers deliberately keeps a non-UTF-8 legacy layer- (with its "replace" default) so unrelated commands still- resolve, so the same tolerance must apply here β the documented- contract is "Composed content string, or None if not found",- not a raw UnicodeDecodeError at composition time.- """- try:- text = layer["path"].read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- return None- extension_id = layer.get("extension_id")- extension_dir = layer.get("extension_dir")- if extension_id and extension_dir:- from ..agents import CommandRegistrar-- text = CommandRegistrar.rewrite_extension_paths(- text, extension_id, extension_dir- )- return text-- # If the top (highest-priority) layer is replace, it wins entirely β- # lower layers are irrelevant regardless of their strategies.- if layers[0]["strategy"] == "replace":- return _read_layer_content(layers[0])-- # Composition: build content bottom-up from the effective base.- # The base is the nearest replace layer scanning from highest priority- # downward. Only layers above the base contribute to composition.- #- # layers is ordered highest-priority first. We process in reverse.- reversed_layers = list(reversed(layers))-- # Find the effective base: scan from highest priority (layers[0]) downward- # to find the nearest replace layer. Only compose layers above that base.- # layers is highest-priority first; reversed_layers is lowest first.- base_layer_idx = None # index in layers[] (highest-priority first)- for idx, layer in enumerate(layers):- if layer["strategy"] == "replace":- base_layer_idx = idx- break-- if base_layer_idx is None:- return None # no replace base found-- # Convert to reversed_layers index- base_reversed_idx = len(layers) - 1 - base_layer_idx- content = _read_layer_content(layers[base_layer_idx])- if content is None:- return None- # Compose only the layers above the base (higher priority = lower index in layers,- # higher index in reversed_layers). Process bottom-up from base+1.- start_idx = base_reversed_idx + 1-- # For command composition, strip frontmatter from each layer to avoid- # leaking YAML metadata into the composed body. The highest-priority- # layer's frontmatter will be reattached at the end.- is_command = template_type == "command"- top_frontmatter_text = None- base_frontmatter_text = None-- def _split_frontmatter(text: str) -> tuple:- """Return (frontmatter_block_with_fences, body) or (None, text).-- Uses line-based fence detection (fence must be ``---`` on its- own line) to avoid false matches on ``---`` inside YAML values.- """- lines = text.splitlines(keepends=True)- if not lines or lines[0].rstrip("\r\n") != "---":- return None, text-- fence_end = -1- for i, line in enumerate(lines[1:], start=1):- if line.rstrip("\r\n") == "---":- fence_end = i- break-- if fence_end == -1:- return None, text-- fm_block = "".join(lines[:fence_end + 1]).rstrip("\r\n")- body = "".join(lines[fence_end + 1:])- return fm_block, body-- if is_command:- fm, body = _split_frontmatter(content)- if fm:- top_frontmatter_text = fm- base_frontmatter_text = fm- content = body-- # Apply composition layers from bottom to top- for layer in reversed_layers[start_idx:]:- try:- layer_content = layer["path"].read_text(encoding="utf-8")- except (OSError, UnicodeDecodeError):- # Same tolerance as _read_layer_content: an unreadable layer- # means the composed result cannot be produced.- return None- strategy = layer["strategy"]-- if is_command:- fm, layer_body = _split_frontmatter(layer_content)- layer_content = layer_body- # Track the highest-priority frontmatter seen;- # replace layers reset both top and base frontmatter since- # they replace the entire command including metadata.- if strategy == "replace":- top_frontmatter_text = fm- base_frontmatter_text = fm- elif fm:- top_frontmatter_text = fm-- if strategy == "replace":- content = layer_content- elif strategy == "prepend":- content = layer_content + "\n\n" + content- elif strategy == "append":- content = content + "\n\n" + layer_content- elif strategy == "wrap":- if template_type == "script":- placeholder = "$CORE_SCRIPT"- else:- placeholder = "{CORE_TEMPLATE}"- if placeholder not in layer_content:- raise PresetValidationError(- f"Wrap strategy in '{layer['source']}' is missing "- f"the {placeholder} placeholder. The wrapper must "- f"contain {placeholder} to indicate where the "- f"lower-priority content should be inserted."- )- content = layer_content.replace(placeholder, content)-- # Reattach the highest-priority frontmatter for commands,- # inheriting scripts/agent_scripts from the base if missing- # and stripping the strategy key (internal-only, not for agent output).- if is_command and top_frontmatter_text:- def _parse_fm_yaml(fm_block: str) -> dict:- """Parse YAML from a frontmatter block (with --- fences)."""- lines = fm_block.splitlines()- # Parse only interior lines (between --- fences)- if len(lines) >= 2:- yaml_lines = lines[1:-1]- else:- yaml_lines = []- try:- return yaml.safe_load("\n".join(yaml_lines)) or {}- except yaml.YAMLError:- return {}-- top_fm = _parse_fm_yaml(top_frontmatter_text)-- # Inherit scripts/agent_scripts from base frontmatter if missing- if base_frontmatter_text and base_frontmatter_text != top_frontmatter_text:- base_fm = _parse_fm_yaml(base_frontmatter_text)- for key in ("scripts", "agent_scripts", "argument-hint"):- if key not in top_fm and key in base_fm:- top_fm[key] = base_fm[key]-- # Strip strategy key β it's an internal composition directive,- # not meant for rendered agent command files- top_fm.pop("strategy", None)-- if top_fm:- top_frontmatter_text = (- "---\n"- + dump_frontmatter(top_fm)- + "\n---"- )- else:- # Empty frontmatter β omit rather than emitting {}- top_frontmatter_text = None-- if top_frontmatter_text:- content = top_frontmatter_text + "\n\n" + content-- return content+from ._manager import (+ _CONSTITUTION_SYNC_PRESET_ID as _CONSTITUTION_SYNC_PRESET_ID,+)+from ._manager import (+ PresetManager as PresetManager,+)+from ._manager import (+ _constitution_is_generated as _constitution_is_generated,+)+from ._manager import (+ _constitution_provenance_matches_preset as _constitution_provenance_matches_preset,+)+from ._manager import (+ _content_sha256 as _content_sha256,+)+from ._manager import (+ _is_comparable_version as _is_comparable_version,+)+from ._manager import (+ _materialize_constitution_template as _materialize_constitution_template,+)+from ._manager_commands import _substitute_core_template as _substitute_core_template+from ._manifest import (+ VALID_PRESET_STRATEGIES as VALID_PRESET_STRATEGIES,+)+from ._manifest import (+ VALID_PRESET_TEMPLATE_TYPES as VALID_PRESET_TEMPLATE_TYPES,+)+from ._manifest import (+ VALID_SCRIPT_STRATEGIES as VALID_SCRIPT_STRATEGIES,+)+from ._manifest import (+ PresetCompatibilityError as PresetCompatibilityError,+)+from ._manifest import (+ PresetError as PresetError,+)+from ._manifest import (+ PresetManifest as PresetManifest,+)+from ._manifest import (+ PresetValidationError as PresetValidationError,+)+from ._registry import PresetRegistry as PresetRegistry+from ._resolver import PresetResolver as PresetResolverdiff --git a/src/specify_cli/presets/_catalog.py b/src/specify_cli/presets/_catalog.pynew file mode 100644index 000000000..a4768cc22--- /dev/null+++ b/src/specify_cli/presets/_catalog.py@@ -0,0 +1,926 @@+"""Preset catalog retrieval and downloads (private domain implementation)."""++import hashlib+import json+import os+import tempfile+from dataclasses import dataclass+from datetime import datetime, timezone+from pathlib import Path+from typing import Any, Dict, List, Optional++import yaml++from .._download_security import (+ archive_format_from_name,+ archive_suffix,+ build_safe_download_path,+ detect_archive_format,+ is_https_or_localhost_http,+)+from ._manifest import PresetError, PresetValidationError+++@dataclass+class PresetCatalogEntry:+ """Represents a single entry in the preset catalog stack."""+ url: str+ name: str+ priority: int+ install_allowed: bool+ description: str = ""+++class PresetCatalog:+ """Manages preset catalog fetching, caching, and searching.++ Supports multi-catalog stacks with priority-based resolution,+ mirroring the extension catalog system.+ """++ DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.json"+ COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/presets/catalog.community.json"+ CACHE_DURATION = 3600 # 1 hour in seconds++ def __init__(self, project_root: Path):+ """Initialize preset catalog manager.++ Args:+ project_root: Root directory of the spec-kit project+ """+ self.project_root = project_root+ self.presets_dir = project_root / ".specify" / "presets"+ self.cache_dir = self.presets_dir / ".cache"+ self.cache_file = self.cache_dir / "catalog.json"+ self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"++ def _validate_catalog_url(self, url: str) -> None:+ """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).++ Args:+ url: URL to validate++ Raises:+ PresetValidationError: If URL is invalid or uses non-HTTPS scheme+ """+ from urllib.parse import urlparse++ try:+ parsed = urlparse(url)+ hostname = parsed.hostname+ # Accessing ``port`` performs urllib's syntax/range validation;+ # ``hostname`` alone does not, so a non-numeric or out-of-range+ # port would otherwise pass validation here and only fail later,+ # at fetch time, as a raw error this function does not translate+ # into PresetValidationError. Mirrors specify_cli.catalogs and+ # bundler/services/adapters.py's copy of this same guard.+ _ = parsed.port+ except ValueError:+ raise PresetValidationError(f"Catalog URL is malformed: {url}") from None+ is_localhost = hostname in ("localhost", "127.0.0.1", "::1")+ if parsed.scheme != "https" and not (+ parsed.scheme == "http" and is_localhost+ ):+ raise PresetValidationError(+ f"Catalog URL must use HTTPS (got {parsed.scheme}://). "+ "HTTP is only allowed for localhost."+ )+ # Check hostname, not netloc: netloc is truthy for host-less URLs like+ # "https://:8080" or "https://user@", so the host guarantee this error+ # promises would not actually hold. hostname is None in those cases (#3209).+ if not hostname:+ raise PresetValidationError(+ "Catalog URL must be a valid URL with a host."+ )++ def _make_request(self, url: str):+ """Build a urllib Request, adding auth headers when a provider matches.++ Delegates to :func:`specify_cli.authentication.http.build_request`.+ """+ from specify_cli.authentication.http import build_request+ return build_request(url)++ def _open_url(+ self,+ url: str,+ timeout: int = 10,+ extra_headers: Optional[Dict[str, str]] = None,+ redirect_validator=None,+ ):+ """Open a URL with provider-based auth, trying each configured provider.++ Delegates to :func:`specify_cli.authentication.http.open_url`.+ *redirect_validator*, when provided, is invoked as ``(old_url, new_url)``+ before EACH redirect hop, so an HTTPS host guarantee can be enforced on+ every intermediate URL, not just the terminal one.+ """+ from specify_cli.authentication.http import open_url+ return open_url(+ url,+ timeout,+ extra_headers=extra_headers,+ redirect_validator=redirect_validator,+ )++ def _resolve_github_release_asset_api_url(+ self,+ download_url: str,+ timeout: int = 60,+ ) -> Optional[str]:+ """Resolve a GitHub release asset URL to its REST API asset URL.++ Passes the ``github`` provider hosts from ``auth.json`` so GitHub+ Enterprise Server release assets resolve via ``/api/v3``.+ """+ from specify_cli.authentication.github_http import (+ resolve_github_release_asset_api_url,+ )+ from specify_cli.authentication.http import github_provider_hosts++ return resolve_github_release_asset_api_url(+ download_url,+ self._open_url,+ timeout=timeout,+ github_hosts=github_provider_hosts(),+ )++ def _validate_catalog_payload(self, catalog_data: Any, url: str) -> None:+ """Validate a parsed preset-catalog payload's shape.++ Applied to both network-fetched and cache-loaded payloads so a+ once-poisoned cache (older spec-kit version, manual edit, upstream+ served a bad payload before the network-side guards were added)+ cannot re-crash ``_get_merged_packs`` on subsequent calls.++ Checking only key presence would let a payload like+ ``{"presets": []}`` or ``{"presets": null}`` slip through here and+ then crash with ``AttributeError: 'list' object has no attribute+ 'items'`` deep inside ``_get_merged_packs``. The sibling+ integration catalog reader already guards both the root object and+ the nested mapping (see ``integrations/catalog.py``); the preset+ catalog must stay consistent so a malformed payload surfaces as+ the user-facing ``Invalid preset catalog format`` error instead of+ a raw Python traceback.++ Args:+ catalog_data: Parsed JSON payload from the catalog source.+ url: Source URL β used in the error message so the user can+ tell which catalog in a multi-catalog stack is malformed.++ Raises:+ PresetError: If the payload's shape is invalid.+ """+ if not isinstance(catalog_data, dict):+ raise PresetError(+ f"Invalid preset catalog format from {url}: "+ "expected a JSON object"+ )+ if (+ "schema_version" not in catalog_data+ or "presets" not in catalog_data+ ):+ raise PresetError(f"Invalid preset catalog format from {url}")+ if not isinstance(catalog_data.get("presets"), dict):+ raise PresetError(+ f"Invalid preset catalog format from {url}: "+ "'presets' must be a JSON object"+ )++ def _load_catalog_config(self, config_path: Path) -> Optional[List[PresetCatalogEntry]]:+ """Load catalog stack configuration from a YAML file.++ Args:+ config_path: Path to preset-catalogs.yml++ Returns:+ Ordered list of PresetCatalogEntry objects, or None if file+ doesn't exist or contains no valid catalog entries.++ Raises:+ PresetValidationError: If any catalog entry has an invalid URL,+ the file cannot be parsed, or a priority value is invalid.+ """+ if not config_path.exists():+ return None+ try:+ data = yaml.safe_load(config_path.read_text(encoding="utf-8"))+ except (yaml.YAMLError, OSError, UnicodeError) as e:+ raise PresetValidationError(+ f"Failed to read catalog config {config_path}: {e}"+ )+ # Do NOT coerce with ``or {}`` here: that also turns a FALSY+ # non-mapping top level (``[]``, ``false``, ``0``, ``''``) into ``{}``+ # and silently swallows it, while a TRUTHY non-mapping (``5``, a bare+ # list) correctly raises below. Only an empty document/explicit+ # ``null`` means "no document".+ if data is None:+ return None+ if not isinstance(data, dict):+ raise PresetValidationError(+ f"Invalid catalog config {config_path}: expected a mapping at root, got {type(data).__name__}"+ )+ # Same asymmetry one nesting level down: the shape check has to run+ # BEFORE the emptiness check, or a FALSY non-list ``catalogs`` value+ # (``{}``, ``''``, ``0``, ``false``) is silently swallowed as "no+ # catalogs" while a TRUTHY non-list (``catalogs: "not-a-list"``)+ # correctly raises. An absent key or an explicit ``catalogs: null``+ # both keep their existing "nothing configured here" behavior.+ catalogs_data = data.get("catalogs")+ if catalogs_data is None:+ return None+ if not isinstance(catalogs_data, list):+ raise PresetValidationError(+ f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"+ )+ if not catalogs_data:+ return None+ entries: List[PresetCatalogEntry] = []+ for idx, item in enumerate(catalogs_data):+ if not isinstance(item, dict):+ raise PresetValidationError(+ f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"+ )+ url = str(item.get("url", "")).strip()+ if not url:+ continue+ self._validate_catalog_url(url)+ raw_priority = item.get("priority", idx + 1)+ # Reject bools explicitly: ``bool`` is a subclass of ``int`` so+ # ``int(True)`` silently returns 1, which would let a YAML+ # ``priority: true`` slip through as a valid priority of 1. The+ # sibling integration-catalog reader in ``catalogs.py`` already+ # guards this; mirror the check here so the three catalog+ # validators stay consistent.+ if isinstance(raw_priority, bool):+ raise PresetValidationError(+ f"Invalid priority for catalog '{item.get('name', idx + 1)}': "+ f"expected integer, got {raw_priority!r}"+ )+ try:+ priority = int(raw_priority)+ except (TypeError, ValueError, OverflowError):+ # OverflowError: int(float("inf")) β a YAML ``priority: .inf``+ # would otherwise escape as an uncaught traceback instead of the+ # clean validation error (mirrors catalogs.py).+ raise PresetValidationError(+ f"Invalid priority for catalog '{item.get('name', idx + 1)}': "+ f"expected integer, got {raw_priority!r}"+ )+ raw_install = item.get("install_allowed", False)+ if isinstance(raw_install, str):+ install_allowed = raw_install.strip().lower() in ("true", "yes", "1")+ else:+ install_allowed = bool(raw_install)+ raw_name = item.get("name")+ name = str(raw_name).strip() if raw_name is not None else ""+ if not name:+ name = f"catalog-{len(entries) + 1}"++ entries.append(PresetCatalogEntry(+ url=url,+ name=name,+ priority=priority,+ install_allowed=install_allowed,+ description=str(item.get("description", "")),+ ))+ entries.sort(key=lambda e: e.priority)+ return entries if entries else None++ def get_active_catalogs(self) -> List[PresetCatalogEntry]:+ """Get the ordered list of active preset catalogs.++ Resolution order:+ 1. SPECKIT_PRESET_CATALOG_URL env var β single catalog replacing all defaults+ 2. Project-level .specify/preset-catalogs.yml+ 3. User-level ~/.specify/preset-catalogs.yml+ 4. Built-in default stack (default + community)++ Returns:+ List of PresetCatalogEntry objects sorted by priority (ascending)++ Raises:+ PresetValidationError: If a catalog URL is invalid+ """+ import sys++ # 1. SPECKIT_PRESET_CATALOG_URL env var replaces all defaults+ if env_value := os.environ.get("SPECKIT_PRESET_CATALOG_URL"):+ catalog_url = env_value.strip()+ self._validate_catalog_url(catalog_url)+ if catalog_url != self.DEFAULT_CATALOG_URL:+ if not getattr(self, "_non_default_catalog_warning_shown", False):+ print(+ "Warning: Using non-default preset catalog. "+ "Only use catalogs from sources you trust.",+ file=sys.stderr,+ )+ self._non_default_catalog_warning_shown = True+ return [PresetCatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_PRESET_CATALOG_URL")]++ # 2. Project-level config overrides all defaults+ project_config_path = self.project_root / ".specify" / "preset-catalogs.yml"+ catalogs = self._load_catalog_config(project_config_path)+ if catalogs is not None:+ return catalogs++ # 3. User-level config+ user_config_path = Path.home() / ".specify" / "preset-catalogs.yml"+ catalogs = self._load_catalog_config(user_config_path)+ if catalogs is not None:+ return catalogs++ # 4. Built-in default stack+ return [+ PresetCatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable presets"),+ PresetCatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed presets (discovery only)"),+ ]++ def get_catalog_url(self) -> str:+ """Get the primary catalog URL.++ Returns the URL of the highest-priority catalog. Kept for backward+ compatibility. Use get_active_catalogs() for full multi-catalog support.++ Returns:+ URL of the primary catalog+ """+ active = self.get_active_catalogs()+ return active[0].url if active else self.DEFAULT_CATALOG_URL++ def _get_cache_paths(self, url: str):+ """Get cache file paths for a given catalog URL.++ For the DEFAULT_CATALOG_URL, uses legacy cache files for backward+ compatibility. For all other URLs, uses URL-hash-based cache files.++ Returns:+ Tuple of (cache_file_path, cache_metadata_path)+ """+ if url == self.DEFAULT_CATALOG_URL:+ return self.cache_file, self.cache_metadata_file+ url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]+ return (+ self.cache_dir / f"catalog-{url_hash}.json",+ self.cache_dir / f"catalog-{url_hash}-metadata.json",+ )++ def _is_url_cache_valid(self, url: str) -> bool:+ """Check if cached catalog for a specific URL is still valid."""+ cache_file, metadata_file = self._get_cache_paths(url)+ if not cache_file.exists() or not metadata_file.exists():+ return False+ try:+ metadata = json.loads(metadata_file.read_text(encoding="utf-8"))+ cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))+ if cached_at.tzinfo is None:+ cached_at = cached_at.replace(tzinfo=timezone.utc)+ age_seconds = (+ datetime.now(timezone.utc) - cached_at+ ).total_seconds()+ return age_seconds < self.CACHE_DURATION+ except (+ json.JSONDecodeError,+ OSError,+ UnicodeError,+ ValueError,+ KeyError,+ TypeError,+ AttributeError,+ ):+ # Cache validity is best-effort: invalid/missing fields, an+ # unreadable metadata file (permissions / disk), a wrongly+ # encoded one (written by a tool using the system locale+ # codec), or a metadata payload that parses to a non-mapping+ # like ``[]`` or ``"oops"`` (so ``metadata.get(...)`` raises+ # ``AttributeError``) all degrade to "cache invalid" so the+ # caller falls through to a network refetch instead of+ # crashing.+ return False++ def _fetch_single_catalog(self, entry: PresetCatalogEntry, force_refresh: bool = False) -> Dict[str, Any]:+ """Fetch a single catalog with per-URL caching.++ Args:+ entry: PresetCatalogEntry describing the catalog to fetch+ force_refresh: If True, bypass cache++ Returns:+ Catalog data dictionary++ Raises:+ PresetError: If catalog cannot be fetched+ """+ # Honor the established package-level patch points during extraction.+ from . import MAX_JSON_CATALOG_BYTES, read_response_limited++ cache_file, metadata_file = self._get_cache_paths(entry.url)++ # Use cache if valid. A previously-cached payload must clear the+ # same shape checks as a freshly-fetched one β otherwise a once-+ # poisoned cache would re-crash on every invocation despite the+ # cache being "valid" by age. If validation fails on the cached+ # read, fall through to the network fetch path so the cache gets+ # refreshed.+ if not force_refresh and self._is_url_cache_valid(entry.url):+ try:+ cached_data = json.loads(cache_file.read_text(encoding="utf-8"))+ self._validate_catalog_payload(cached_data, entry.url)+ return cached_data+ except (json.JSONDecodeError, OSError, UnicodeError, PresetError):+ # Cache is best-effort: a JSON-decode failure, an OS-level+ # read failure (permissions / disk / handle limit), or a+ # text-encoding failure on a cache file written by an+ # older client all fall through to the network fetch path.+ # Only the network failure is surfaced to the caller.+ pass++ try:+ # Validate EVERY redirect hop (not just the terminal URL): an+ # https -> http -> attacker-controlled-https chain would pass a+ # final-URL-only check while the insecure intermediate hop lets a+ # network attacker rewrite the next redirect. redirect_validator runs+ # before each hop; the final geturl() check is retained as a+ # belt-and-braces guard. Mirrors bundler/services/adapters.py.+ def _validate_redirect(_old_url: str, new_url: str) -> None:+ self._validate_catalog_url(new_url)++ with self._open_url(+ entry.url, timeout=10, redirect_validator=_validate_redirect+ ) as response:+ final_url = response.geturl()+ if final_url != entry.url:+ self._validate_catalog_url(final_url)+ catalog_data = json.loads(+ read_response_limited(+ response,+ max_bytes=MAX_JSON_CATALOG_BYTES,+ error_type=PresetError,+ label=f"preset catalog {entry.url}",+ )+ )++ self._validate_catalog_payload(catalog_data, entry.url)++ # Both files are written explicitly as UTF-8 to match the+ # ``read_text(encoding="utf-8")`` on the read side and the+ # ``integrations/catalog.py`` precedent. Without this,+ # platforms whose default encoding isn't UTF-8 would write+ # locale-encoded bytes the read path can't decode, forcing an+ # unnecessary refetch on every invocation. The write itself+ # is best-effort like the read side: an unwritable cache dir+ # (read-only checkout, permissions) must not be re-raised as+ # a ``PresetError`` for a payload that was already fetched+ # and validated.+ try:+ self.cache_dir.mkdir(parents=True, exist_ok=True)+ cache_file.write_text(+ json.dumps(catalog_data, indent=2), encoding="utf-8"+ )+ metadata = {+ "cached_at": datetime.now(timezone.utc).isoformat(),+ "catalog_url": entry.url,+ }+ metadata_file.write_text(+ json.dumps(metadata, indent=2), encoding="utf-8"+ )+ except OSError:+ pass # Cache is best-effort; proceed with fetched data++ return catalog_data++ except (ImportError, Exception) as e:+ if isinstance(e, PresetError):+ raise+ raise PresetError(+ f"Failed to fetch preset catalog from {entry.url}: {e}"+ )++ def _get_merged_packs(self, force_refresh: bool = False) -> Dict[str, Dict[str, Any]]:+ """Fetch and merge presets from all active catalogs.++ Higher-priority catalogs (lower priority number) win on ID conflicts.++ Returns:+ Merged dictionary of pack_id -> pack_data+ """+ active_catalogs = self.get_active_catalogs()+ merged: Dict[str, Dict[str, Any]] = {}++ for entry in reversed(active_catalogs):+ try:+ data = self._fetch_single_catalog(entry, force_refresh)+ for pack_id, pack_data in data.get("presets", {}).items():+ # Per-entry guard: ``_fetch_single_catalog`` already+ # validates that ``data["presets"]`` is a mapping, but it+ # does not (and should not) validate every entry shape+ # there β one malformed entry shouldn't poison an+ # otherwise valid catalog. Skip non-mapping entries here+ # so a payload like ``{"presets": {"foo": [], "bar":+ # {...}}}`` still merges the valid entries without+ # crashing on ``**pack_data``. Mirrors+ # ``integrations/catalog.py:245``.+ if not isinstance(pack_data, dict):+ continue+ pack_data_with_catalog = {**pack_data, "_catalog_name": entry.name, "_install_allowed": entry.install_allowed}+ merged[pack_id] = pack_data_with_catalog+ except PresetError:+ continue++ return merged++ def is_cache_valid(self) -> bool:+ """Check if cached catalog is still valid.++ Returns ``False`` for any read/decoding failure on the metadata+ file (missing fields, malformed JSON, permissions / disk errors,+ wrong text encoding) so callers fall through to a network refetch+ instead of crashing. Treating cache validity as best-effort+ matches the contract used by ``_is_url_cache_valid`` above.++ Returns:+ True if cache exists and is within cache duration+ """+ if not self.cache_file.exists() or not self.cache_metadata_file.exists():+ return False++ try:+ metadata = json.loads(+ self.cache_metadata_file.read_text(encoding="utf-8")+ )+ cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))+ if cached_at.tzinfo is None:+ cached_at = cached_at.replace(tzinfo=timezone.utc)+ age_seconds = (+ datetime.now(timezone.utc) - cached_at+ ).total_seconds()+ return age_seconds < self.CACHE_DURATION+ except (+ json.JSONDecodeError,+ OSError,+ UnicodeError,+ ValueError,+ KeyError,+ TypeError,+ AttributeError,+ ):+ # ``AttributeError`` covers the case where the metadata file+ # parses to a non-mapping (``[]``, ``"oops"``, ``42``) so+ # ``metadata.get(...)`` would otherwise crash. All decode /+ # shape failures degrade to "cache invalid" so the caller+ # falls through to a network refetch.+ return False++ def fetch_catalog(self, force_refresh: bool = False) -> Dict[str, Any]:+ """Fetch preset catalog from URL or cache.++ Args:+ force_refresh: If True, bypass cache and fetch from network++ Returns:+ Catalog data dictionary++ Raises:+ PresetError: If catalog cannot be fetched+ """+ from . import MAX_JSON_CATALOG_BYTES, read_response_limited++ catalog_url = self.get_catalog_url()++ # Match the ``_fetch_single_catalog`` cache contract: a poisoned+ # or unreadable cache silently falls through to a network refetch+ # rather than crashing the caller. ``_validate_catalog_payload``+ # is reused here so a cache written by an older client+ # (pre-validation) is rejected and refreshed instead of returning+ # the stale malformed payload.+ if not force_refresh and self.is_cache_valid():+ try:+ metadata = json.loads(+ self.cache_metadata_file.read_text(encoding="utf-8")+ )+ if metadata.get("catalog_url") == catalog_url:+ cached_data = json.loads(+ self.cache_file.read_text(encoding="utf-8")+ )+ self._validate_catalog_payload(cached_data, catalog_url)+ return cached_data+ except (json.JSONDecodeError, OSError, UnicodeError, PresetError):+ # Cache is corrupt, unreadable, or fails the shape check;+ # fall through to network fetch.+ pass++ try:+ # Same redirect hardening as _fetch_single_catalog: validate every+ # redirect hop AND the final URL so this legacy single-catalog path+ # is not vulnerable to an HTTPS->HTTP redirected payload either.+ def _validate_redirect(_old_url: str, new_url: str) -> None:+ self._validate_catalog_url(new_url)++ with self._open_url(+ catalog_url, timeout=10, redirect_validator=_validate_redirect+ ) as response:+ final_url = response.geturl()+ if final_url != catalog_url:+ self._validate_catalog_url(final_url)+ catalog_data = json.loads(+ read_response_limited(+ response,+ max_bytes=MAX_JSON_CATALOG_BYTES,+ error_type=PresetError,+ label=f"preset catalog {catalog_url}",+ )+ )++ # Validate catalog structure. Reuses the same helper as+ # ``_fetch_single_catalog`` so all three branches (root type,+ # missing keys, nested-mapping type) stay consistent.+ self._validate_catalog_payload(catalog_data, catalog_url)++ # Save to cache. Explicit UTF-8 on both writes mirrors the+ # ``read_text(encoding="utf-8")`` on the read side and the+ # ``integrations/catalog.py`` precedent β otherwise platforms+ # whose default encoding isn't UTF-8 would write+ # locale-encoded bytes the read path can't decode, forcing an+ # unnecessary refetch on every invocation. Like the read+ # side, the write is best-effort: an unwritable cache dir+ # must not be re-raised as a ``PresetError`` for a payload+ # that was already fetched and validated.+ try:+ self.cache_dir.mkdir(parents=True, exist_ok=True)+ self.cache_file.write_text(+ json.dumps(catalog_data, indent=2), encoding="utf-8"+ )++ metadata = {+ "cached_at": datetime.now(timezone.utc).isoformat(),+ "catalog_url": catalog_url,+ }+ self.cache_metadata_file.write_text(+ json.dumps(metadata, indent=2), encoding="utf-8"+ )+ except OSError:+ pass # Cache is best-effort; proceed with fetched data++ return catalog_data++ except (ImportError, Exception) as e:+ if isinstance(e, PresetError):+ raise+ raise PresetError(+ f"Failed to fetch preset catalog from {catalog_url}: {e}"+ )++ def search(+ self,+ query: Optional[str] = None,+ tag: Optional[str] = None,+ author: Optional[str] = None,+ ) -> List[Dict[str, Any]]:+ """Search catalog for presets.++ Searches across all active catalogs (merged by priority) so that+ community and custom catalogs are included in results.++ Args:+ query: Search query (searches name, description, tags)+ tag: Filter by specific tag+ author: Filter by author name++ Returns:+ List of matching preset metadata+ """+ try:+ packs = self._get_merged_packs()+ except PresetError:+ return []++ results = []++ for pack_id, pack_data in packs.items():+ if author:+ author_val = pack_data.get("author", "")+ if not isinstance(author_val, str):+ author_val = str(author_val) if author_val is not None else ""+ if author_val.lower() != author.lower():+ continue++ if tag:+ raw_tags = pack_data.get("tags", [])+ tags_list = raw_tags if isinstance(raw_tags, list) else []+ if tag.lower() not in [+ str(t).lower() for t in tags_list+ ]:+ continue++ if query:+ query_lower = query.lower()+ raw_tags = pack_data.get("tags", [])+ tags_list = raw_tags if isinstance(raw_tags, list) else []+ name_val = pack_data.get("name", "")+ desc_val = pack_data.get("description", "")+ searchable_text = " ".join(+ [+ str(name_val) if name_val is not None else "",+ str(desc_val) if desc_val is not None else "",+ pack_id,+ ]+ + [str(t) for t in tags_list]+ ).lower()++ if query_lower not in searchable_text:+ continue++ results.append({**pack_data, "id": pack_id})++ return results++ def get_pack_info(+ self, pack_id: str+ ) -> Optional[Dict[str, Any]]:+ """Get detailed information about a specific preset.++ Searches across all active catalogs (merged by priority).++ Args:+ pack_id: ID of the preset++ Returns:+ Pack metadata or None if not found+ """+ try:+ packs = self._get_merged_packs()+ except PresetError:+ return None++ if pack_id in packs:+ return {**packs[pack_id], "id": pack_id}+ return None++ def download_pack(+ self, pack_id: str, target_dir: Optional[Path] = None+ ) -> Path:+ """Download a preset archive from a catalog.++ Args:+ pack_id: ID of the preset to download+ target_dir: Directory to save the archive++ Returns:+ Path to the downloaded archive++ Raises:+ PresetError: If pack not found or download fails+ """+ import urllib.error++ from . import read_response_limited, verify_archive_sha256++ pack_info = self.get_pack_info(pack_id)+ if not pack_info:+ raise PresetError(+ f"Preset '{pack_id}' not found in catalog"+ )++ # Bundled presets without a download URL must be installed locally+ if pack_info.get("bundled") and not pack_info.get("download_url"):+ from ..extensions import REINSTALL_COMMAND+ raise PresetError(+ f"Preset '{pack_id}' is bundled with spec-kit and has no download URL. "+ f"It should be installed from the local package. "+ f"Use 'specify preset add {pack_id}' to install from the bundled package, "+ f"or reinstall spec-kit if the bundled files are missing: {REINSTALL_COMMAND}"+ )++ if not pack_info.get("_install_allowed", True):+ catalog_name = pack_info.get("_catalog_name", "unknown")+ raise PresetError(+ f"Preset '{pack_id}' is from the '{catalog_name}' catalog which does not allow installation. "+ f"Use --from with the preset's repository URL instead."+ )++ download_url = pack_info.get("download_url")+ if not download_url:+ raise PresetError(+ f"Preset '{pack_id}' has no download URL"+ )+ if not isinstance(download_url, str):+ raise PresetError(+ f"Preset download URL is malformed: {download_url}"+ )++ from urllib.parse import urlparse++ # A malformed authority (e.g. an unterminated IPv6 bracket+ # "https://[::1") makes urlparse / hostname access raise ValueError.+ # The download_url comes from catalog payload data, so surface a clean+ # PresetError rather than leaking a raw ValueError past the command+ # handler (which only catches PresetError). Mirrors catalogs (#3435)+ # and workflows/catalog.py (#3484).+ try:+ parsed = urlparse(download_url)+ hostname = parsed.hostname+ parsed.port+ except ValueError:+ raise PresetError(+ f"Preset download URL is malformed: {download_url}"+ ) from None+ if not hostname:+ raise PresetError(+ f"Preset download URL is malformed: {download_url}"+ )+ if not is_https_or_localhost_http(download_url):+ raise PresetError(+ f"Preset download URL must use HTTPS: {download_url}"+ )++ if target_dir is None:+ target_dir = self.cache_dir / "downloads"+ target_dir = Path(target_dir)+ version = pack_info.get("version", "unknown")+ declared_format = archive_format_from_name(download_url)+ build_safe_download_path(+ target_dir,+ pack_id,+ version,+ error_type=PresetError,+ label="preset",+ suffix=archive_suffix(declared_format or "tar.gz"),+ )+ target_dir.mkdir(parents=True, exist_ok=True)++ original_download_url = download_url+ extra_headers = None+ resolved_download_url = self._resolve_github_release_asset_api_url(download_url)+ if resolved_download_url:+ download_url = resolved_download_url+ extra_headers = {"Accept": "application/octet-stream"}++ staging_path: Path | None = None+ try:+ with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:+ archive_data = read_response_limited(+ response,+ error_type=PresetError,+ label=f"preset '{pack_id}' download",+ )+ final_url = (+ response.geturl()+ if hasattr(response, "geturl")+ else download_url+ )+ content_type = (+ response.getheader("Content-Type")+ if hasattr(response, "getheader")+ else None+ )++ verify_archive_sha256(+ archive_data, pack_info.get("sha256"), pack_id, PresetError+ )++ with tempfile.NamedTemporaryFile(+ prefix="preset-download-",+ suffix=".archive",+ dir=target_dir,+ delete=False,+ ) as staging_file:+ staging_path = Path(staging_file.name)+ staging_file.write(archive_data)+ archive_format = detect_archive_format(+ staging_path,+ source_name=(+ final_url+ if archive_format_from_name(final_url) is not None+ else original_download_url+ ),+ content_type=content_type,+ error_type=PresetError,+ )+ archive_path = build_safe_download_path(+ target_dir,+ pack_id,+ version,+ error_type=PresetError,+ label="preset",+ suffix=archive_suffix(archive_format),+ )+ os.replace(staging_path, archive_path)+ staging_path = None+ return archive_path++ except urllib.error.URLError as e:+ raise PresetError(+ f"Failed to download preset from {download_url}: {e}"+ )+ except IOError as e:+ raise PresetError(f"Failed to save preset archive: {e}")+ finally:+ if staging_path is not None:+ staging_path.unlink(missing_ok=True)++ def clear_cache(self):+ """Clear all catalog cache files, including per-URL hashed caches."""+ if self.cache_dir.exists():+ for f in self.cache_dir.iterdir():+ if f.is_file() and f.name.startswith("catalog"):+ f.unlink(missing_ok=True)diff --git a/src/specify_cli/presets/_manager.py b/src/specify_cli/presets/_manager.pynew file mode 100644index 000000000..33274dfdf--- /dev/null+++ b/src/specify_cli/presets/_manager.py@@ -0,0 +1,969 @@+"""Preset installation, removal, and lifecycle coordination (private)."""++import hashlib+import json+import shutil+import tempfile+from pathlib import Path+from typing import Any, Dict, List, Optional, Set++from packaging import version as pkg_version+from packaging.specifiers import InvalidSpecifier, SpecifierSet++from .._download_security import safe_extract_archive+from .._init_options import is_ai_skills_enabled, resolve_active_agent_for_registration+from .._utils import version_satisfies+from ..extensions import REINSTALL_COMMAND, normalize_priority+from ..shared_infra import (+ _ensure_safe_shared_destination,+ _ensure_safe_shared_directory,+ _write_shared_bytes,+ _write_shared_text,+)+from ._manager_commands import _PresetCommandMethods+from ._manager_skills import _PresetSkillMethods+from ._manifest import (+ PresetCompatibilityError,+ PresetError,+ PresetManifest,+ PresetValidationError,+)+from ._registry import PresetRegistry+from ._resolver import PresetResolver++_CONSTITUTION_PROVENANCE_FILE = ".constitution-template.json"+_CONSTITUTION_SYNC_PRESET_ID = "constitution-sync"+++def _content_sha256(content: bytes) -> str:+ return hashlib.sha256(content).hexdigest()+++def _is_comparable_version(value: str) -> bool:+ """Return whether a recorded version can be evaluated against a specifier.++ ``version_satisfies()`` answers "does not satisfy" for an unparseable+ version, which is indistinguishable from a genuine mismatch. Callers that+ need to tell those apart check here first.+ """+ try:+ pkg_version.Version(value)+ except pkg_version.InvalidVersion:+ return False+ return True+++def _constitution_is_generated(+ project_root: Path,+ memory_constitution: Path,+ resolver: "PresetResolver",+) -> bool:+ """Return whether the live constitution is an unchanged generated file."""+ _ensure_safe_shared_destination(project_root, memory_constitution)+ content = memory_constitution.read_bytes()+ provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE+ _ensure_safe_shared_destination(project_root, provenance)++ if provenance.exists():+ try:+ metadata = json.loads(provenance.read_text(encoding="utf-8"))+ except (json.JSONDecodeError, UnicodeDecodeError):+ return False+ return (+ isinstance(metadata, dict)+ and metadata.get("sha256") == _content_sha256(content)+ )++ # Older projects have no provenance sidecar. Only the immutable bundled or+ # source-checkout core template is safe to treat as generated.+ core = resolver._find_bundled_core(+ "constitution-template", "template", ".md"+ )+ return core is not None and core.read_bytes() == content+++def _constitution_provenance_matches_preset(+ project_root: Path,+ memory_constitution: Path,+ pack_id: str,+ pack_version: str,+) -> bool:+ """Return whether provenance identifies a preset as the materialized source."""+ provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE+ if not provenance.parent.exists():+ return False+ _ensure_safe_shared_destination(project_root, provenance)+ if not provenance.exists():+ return False+ try:+ metadata = json.loads(provenance.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError, UnicodeDecodeError):+ return False+ return (+ isinstance(metadata, dict)+ and metadata.get("source") == f"{pack_id} v{pack_version}"+ )+++def _materialize_constitution_template(+ project_root: Path,+ memory_constitution: Path,+) -> str | None:+ """Materialize constitution-template content into memory/constitution.md.++ Returns:+ "copied" when the winning layer is ``replace`` and the source file is+ copied verbatim; "composed" when a composing strategy is materialized+ via ``resolve_content``; ``None`` when no constitution template resolves.+ """+ resolver = PresetResolver(project_root)+ layers = resolver.collect_all_layers("constitution-template", "template")+ if not layers:+ return None++ top_layer = layers[0]+ if top_layer["strategy"] == "replace":+ content = top_layer["path"].read_bytes()+ result = "copied"+ else:+ composed_content = resolver.resolve_content("constitution-template", "template")+ if composed_content is None:+ return None+ content = composed_content.encode("utf-8")+ result = "composed"++ _ensure_safe_shared_directory(project_root, memory_constitution.parent)+ _write_shared_bytes(project_root, memory_constitution, content)+ provenance = memory_constitution.parent / _CONSTITUTION_PROVENANCE_FILE+ _write_shared_text(+ project_root,+ provenance,+ json.dumps(+ {+ "sha256": _content_sha256(content),+ "source": top_layer["source"],+ },+ indent=2,+ )+ + "\n",+ )+ return result+++class PresetManager(_PresetCommandMethods, _PresetSkillMethods):+ """Manages preset lifecycle: installation, removal, updates."""++ def __init__(self, project_root: Path):+ """Initialize preset manager.++ Args:+ project_root: Path to project root directory+ """+ self.project_root = project_root+ self.presets_dir = project_root / ".specify" / "presets"+ self.registry = PresetRegistry(self.presets_dir)++ def check_compatibility(+ self,+ manifest: PresetManifest,+ speckit_version: str+ ) -> bool:+ """Check if preset is compatible with current spec-kit version.++ Args:+ manifest: Preset manifest+ speckit_version: Current spec-kit version++ Returns:+ True if compatible++ Raises:+ PresetCompatibilityError: If pack is incompatible+ """+ required = manifest.requires_speckit_version+ # Defense in depth: the manifest validator now rejects a non-string+ # requires.speckit_version, but this method is public and also reachable+ # with a hand-built manifest object. ``InvalidSpecifier`` alone does not+ # cover a non-string -- scalars raise TypeError from the constructor, and+ # a list/dict is iterable so it constructs here and only breaks inside+ # .contains(). Reject up front so this always reports a+ # PresetCompatibilityError.+ if not isinstance(required, str):+ raise PresetCompatibilityError(+ "Invalid version specifier: expected a string, got "+ f"{type(required).__name__} ({required!r})"+ )+ try:+ SpecifierSet(required) # Just to validate+ except InvalidSpecifier:+ raise PresetCompatibilityError(f"Invalid version specifier: {required}")++ if not version_satisfies(speckit_version, required):+ raise PresetCompatibilityError(+ f"Preset requires spec-kit {required}, "+ f"but {speckit_version} is installed.\n"+ f"Upgrade spec-kit with: {REINSTALL_COMMAND}"+ )++ return True++ def find_unmet_extension_dependencies(+ self,+ manifest: PresetManifest+ ) -> List[Dict[str, Any]]:+ """Find declared extension dependencies that are not satisfied.++ Reports rather than raises. A preset whose overrides call into an+ extension is written to degrade safely -- without the extension the+ core workflow still runs -- so a missing dependency is a warning, not+ an install failure. See issue #4231.++ Args:+ manifest: Preset manifest to inspect++ Returns:+ One entry per unsatisfied dependency, each with ``id``, the+ requested ``version`` specifier (``None`` when unconstrained), the+ ``installed`` version (``None`` when absent or unusable), and a+ ``reason`` of ``"missing"``, ``"corrupt"``, ``"stale"``,+ ``"disabled"``, or ``"version"``. Optional dependencies+ (``required: false``) are never reported.++ An unreadable registry yields no results rather than raising, since+ this runs after the install has already succeeded.++ A registry version that cannot be parsed is treated as+ uncomparable, not as a mismatch: the extension is installed and+ usable, and only its recorded version is unreadable. An extension+ present on disk but absent from the registry is likewise treated as+ satisfied, because resolution admits unregistered directories.+ """+ # Defense in depth, mirroring check_compatibility(): this method is+ # public and also reachable with a hand-built manifest object that+ # predates this field. A manifest without it declares nothing.+ candidates = getattr(manifest, "requires_extensions", None)+ if not isinstance(candidates, list):+ return []++ # Collapse exact repeats so a manifest naming the same dependency twice+ # warns once. Two entries for one id with *different* constraints are+ # kept, since both genuinely have to hold.+ declared: List[Dict[str, Any]] = []+ seen: Set[tuple] = set()+ for dep in candidates:+ if not isinstance(dep, dict) or not dep.get("required", True):+ continue+ key = (dep.get("id"), dep.get("version"))+ if key in seen:+ continue+ seen.add(key)+ declared.append(dep)+ if not declared:+ return []++ extensions_dir = self.project_root / ".specify" / "extensions"+ try:+ from . import ExtensionRegistry++ registry = ExtensionRegistry(extensions_dir)+ registered_ids = registry.keys()+ registry_corrupt = registry.is_corrupt()+ except OSError:+ # Both reads can raise: _load() recovers from malformed content but+ # deliberately lets OSError through, and is_corrupt() re-reads the+ # file. This check runs *after* the install has completed, and+ # preset_add only handles preset-domain errors, so letting that+ # escape would turn a finished install into a traceback over a+ # warning. An unreadable registry simply cannot be inspected.+ return []++ unmet: List[Dict[str, Any]] = []++ for dep in declared:+ metadata = registry.get(dep["id"])+ if metadata is None:+ # An absent registry entry does not mean the extension is+ # unusable. _get_all_extensions_by_priority() admits a safe+ # on-disk directory as an unregistered extension at implicit+ # priority 10, so it resolves and the preset works -- but only+ # when the registry is readable, since a corrupt one makes that+ # path fail closed and contribute nothing.+ #+ # get() returns None for a corrupted (non-dict) entry as well as+ # an absent one, but keys() retains corrupted ids -- both so+ # resolution does not re-admit their directories as+ # unregistered, and because is_installed() still counts them, so+ # a plain `extension add` would be refused as already installed.+ # That is a different state from absent, and needs a different+ # remedy.+ if dep["id"] in registered_ids:+ unmet.append({**dep, "installed": None, "reason": "corrupt"})+ continue+ if (+ (extensions_dir / dep["id"]).is_dir()+ and PresetResolver._is_safe_registry_id(dep["id"])+ and not registry_corrupt+ ):+ # Unregistered means no recorded version, so a constraint+ # cannot be evaluated -- uncomparable, not unsatisfied.+ continue+ unmet.append({**dep, "installed": None, "reason": "missing"})+ continue++ installed_version = metadata.get("version")+ installed_version = (+ installed_version if isinstance(installed_version, str) else None+ )++ # A registry entry is not proof the extension can contribute. If+ # its directory is gone, PresetResolver skips it outright (both+ # template lookup and layer collection guard on ``is_dir()``), so+ # the preset is as inert as if it were never installed -- but the+ # surviving entry would otherwise read as satisfied.+ if not (extensions_dir / dep["id"]).is_dir():+ unmet.append(+ {**dep, "installed": installed_version, "reason": "stale"}+ )+ continue++ # A disabled extension is registered but contributes nothing:+ # resolution skips it (see _collect_extension_layers), so the+ # preset is just as inert as if it were absent. Report it before+ # any version check -- enabling it is the prerequisite, and the+ # version may well be fine once it is.+ if not metadata.get("enabled", True):+ unmet.append(+ {**dep, "installed": installed_version, "reason": "disabled"}+ )+ continue++ constraint = dep["version"]+ if not constraint:+ continue++ # A version that cannot be compared is not a mismatch. Absent or+ # non-string is one way to be unusable; an unparseable string such+ # as "unknown" is another, and version_satisfies() cannot tell them+ # apart -- it catches InvalidVersion and returns False, which would+ # report a mismatch against a version nobody can evaluate. Check+ # parseability up front so only real comparisons reach the warning.+ if installed_version is None or not _is_comparable_version(installed_version):+ continue+ if not version_satisfies(installed_version, constraint):+ unmet.append(+ {**dep, "installed": installed_version, "reason": "version"}+ )++ return unmet++ def install_from_directory(+ self,+ source_dir: Path,+ speckit_version: str,+ priority: int = 10,+ force: bool = False,+ *,+ catalog_name: str | None = None,+ ) -> PresetManifest:+ """Install preset from a local directory.++ Args:+ source_dir: Path to preset directory+ speckit_version: Current spec-kit version+ priority: Resolution priority (lower = higher precedence, default 10)+ force: If True and the preset is already installed, remove it first++ Returns:+ Installed preset manifest++ Raises:+ PresetValidationError: If manifest is invalid or priority is invalid+ PresetCompatibilityError: If pack is incompatible+ """+ # Validate priority+ if priority < 1:+ raise PresetValidationError("Priority must be a positive integer (1 or higher)")++ manifest_path = source_dir / "preset.yml"+ manifest = PresetManifest(manifest_path)++ self.check_compatibility(manifest, speckit_version)++ if self.registry.is_installed(manifest.id):+ if not force:+ raise PresetError(+ f"Preset '{manifest.id}' is already installed. "+ f"Use 'specify preset remove {manifest.id}' first."+ )+ self.remove(manifest.id)++ dest_dir = self.presets_dir / manifest.id+ if dest_dir.exists():+ shutil.rmtree(dest_dir)++ shutil.copytree(source_dir, dest_dir)++ # Pre-register the preset so that composition resolution can see it+ # in the priority stack when resolving composed command content.+ normalized_catalog_name = (+ catalog_name.strip() if isinstance(catalog_name, str) else ""+ )+ source = (+ {"kind": "catalog", "catalog": normalized_catalog_name}+ if normalized_catalog_name+ else "local"+ )+ self.registry.add(manifest.id, {+ "version": manifest.version,+ "source": source,+ "manifest_hash": manifest.get_hash(),+ "enabled": True,+ "priority": priority,+ "registered_commands": {},+ "registered_skills": {},+ })++ registered_commands: Dict[str, List[str]] = {}+ registered_skills: Dict[str, List[str]] = {}+ try:+ # Register command overrides with AI agents and persist the result+ # immediately so cleanup can recover even if installation stops+ # before later phases complete.+ registered_commands = self._register_commands(manifest, dest_dir)+ self.registry.update(manifest.id, {+ "registered_commands": registered_commands,+ })++ # Update corresponding skills when skills mode was previously used+ # and persist that result as well.+ registered_skills = self._register_skills(manifest, dest_dir)+ self.registry.update(manifest.id, {+ "registered_skills": registered_skills,+ })+ except Exception:+ # Roll back all side effects. _register_skills persists each+ # successful write immediately, so reload that partial map when+ # a later template fails before the call can return.+ if registered_commands:+ self._unregister_commands(registered_commands)+ persisted_metadata = self.registry.get(manifest.id) or {}+ persisted_skills = persisted_metadata.get(+ "registered_skills", registered_skills+ )+ if persisted_skills:+ self._unregister_skills(+ persisted_skills, dest_dir, restore_from_bundled_core=True+ )+ try:+ if dest_dir.exists():+ shutil.rmtree(dest_dir)+ except OSError:+ pass # best-effort cleanup; don't mask the original error+ self.registry.remove(manifest.id)+ raise++ # Reconcile all affected commands from the full priority stack so that+ # install order doesn't determine the winning command file.+ cmd_names = [+ t["name"]+ for t in manifest.templates+ if t.get("type") == "command"+ ]+ if cmd_names:+ try:+ self._reconcile_composed_commands(cmd_names)+ self._reconcile_skills(cmd_names)+ except Exception as exc:+ import warnings+ warnings.warn(+ f"Post-install reconciliation failed for {manifest.id}: {exc}. "+ f"Agent command files may not reflect the current priority stack.",+ stacklevel=2,+ )++ # TODO: constitution-sync is a named preset with core-owned side effects.+ # Give synchronization an explicit owner without changing its opt-in+ # behavior or overwriting authored constitutions.+ # Materialize constitution-template changes only for projects that opt+ # into the constitution-sync preset. The core /constitution command+ # resolves this template on demand; constitution-sync preserves the+ # previous install-time behavior for teams that want reviewed snapshots.+ self._seed_constitution_from_preset(manifest, dest_dir)++ return manifest++ def _seed_constitution_from_preset(+ self, manifest: PresetManifest, preset_dir: Path+ ) -> None:+ """Seed memory/constitution.md when constitution-sync opts into snapshots.++ Installing constitution-sync itself materializes the currently resolved+ stack. Later preset installs only reconcile when they provide a+ ``constitution-template``. Authored constitutions are never overwritten.+ """+ provides_constitution = manifest.id == _CONSTITUTION_SYNC_PRESET_ID or any(+ t.get("type") == "template" and t.get("name") == "constitution-template"+ for t in manifest.templates+ ) or any(+ (preset_dir / relative_path).is_file()+ for relative_path in (+ "templates/constitution-template.md",+ "constitution-template.md",+ )+ )+ if not provides_constitution:+ return++ self.reconcile_constitution(+ f"Failed to seed constitution from preset {manifest.id}",+ create_if_missing=True,+ )++ def reconcile_constitution(+ self, failure_context: str, *, create_if_missing: bool = False+ ) -> None:+ """Reconcile an opted-in generated constitution without failing a change."""+ try:+ self._reconcile_constitution(create_if_missing=create_if_missing)+ except (OSError, UnicodeDecodeError, PresetValidationError, ValueError) as exc:+ import warnings++ warnings.warn(+ f"{failure_context}: {exc}.",+ stacklevel=2,+ )++ def _reconcile_constitution(self, *, create_if_missing: bool = False) -> None:+ """Materialize the winning layer when constitution-sync is enabled."""+ sync_metadata = self.registry.get(_CONSTITUTION_SYNC_PRESET_ID)+ if sync_metadata is None or not sync_metadata.get("enabled", True):+ return++ memory_constitution = (+ self.project_root / ".specify" / "memory" / "constitution.md"+ )+ if not memory_constitution.exists() and not create_if_missing:+ return+ resolver = PresetResolver(self.project_root)+ if memory_constitution.exists() and not _constitution_is_generated(+ self.project_root, memory_constitution, resolver+ ):+ return+ _materialize_constitution_template(self.project_root, memory_constitution)++ def install_from_archive(+ self,+ archive_path: Path,+ speckit_version: str,+ priority: int = 10,+ force: bool = False,+ *,+ catalog_name: str | None = None,+ ) -> PresetManifest:+ """Install a preset from a supported archive.++ Args:+ archive_path: Path to a .zip, .tar.gz, or .tgz archive+ speckit_version: Current spec-kit version+ priority: Resolution priority (lower = higher precedence, default 10)+ force: If True and the preset is already installed, remove it first++ Returns:+ Installed preset manifest++ Raises:+ PresetValidationError: If manifest is invalid or priority is invalid+ PresetCompatibilityError: If pack is incompatible+ """+ # Validate priority early+ if priority < 1:+ raise PresetValidationError("Priority must be a positive integer (1 or higher)")++ with tempfile.TemporaryDirectory() as tmpdir:+ temp_path = Path(tmpdir)++ safe_extract_archive(+ archive_path,+ temp_path,+ error_type=PresetValidationError,+ )++ pack_dir = temp_path+ manifest_path = pack_dir / "preset.yml"++ if not manifest_path.exists():+ subdirs = [d for d in temp_path.iterdir() if d.is_dir()]+ if len(subdirs) == 1:+ pack_dir = subdirs[0]+ manifest_path = pack_dir / "preset.yml"++ if not manifest_path.exists():+ raise PresetValidationError(+ "No preset.yml found in archive"+ )++ return self.install_from_directory(+ pack_dir,+ speckit_version,+ priority,+ force=force,+ catalog_name=catalog_name,+ )++ def install_from_zip(+ self,+ zip_path: Path,+ speckit_version: str,+ priority: int = 10,+ force: bool = False,+ *,+ catalog_name: str | None = None,+ ) -> PresetManifest:+ """Backward-compatible wrapper for archive installation."""+ return self.install_from_archive(+ zip_path,+ speckit_version,+ priority,+ force=force,+ catalog_name=catalog_name,+ )++ def remove(self, pack_id: str) -> bool:+ """Remove an installed preset.++ Args:+ pack_id: Preset ID++ Returns:+ True if pack was removed+ """+ if not self.registry.is_installed(pack_id):+ return False++ metadata = self.registry.get(pack_id)+ # Restore original skills when preset is removed+ registered_skills = metadata.get("registered_skills", []) if metadata else []+ if isinstance(registered_skills, list) and registered_skills:+ # Legacy flat-list registries predate per-agent provenance+ # tracking. Migration to the per-agent dict form previously+ # only happened during a rescaffold (register_enabled_presets_+ # for_agent); if the *first* post-upgrade operation is instead+ # `preset remove` (no intervening use/upgrade), the legacy+ # branch of _unregister_skills restores only the currently+ # active agent's directory, leaving this preset's overrides in+ # every previously active agent's directory orphaned. Infer+ # real per-agent ownership from the on-disk preset marker now,+ # while pack_id is still known, and hand the resulting mapping+ # through the same dict-based cleanup path already used for+ # non-legacy registries (#2948).+ from .. import load_init_options++ init_opts = load_init_options(self.project_root)+ fallback_agent = init_opts.get("ai") if isinstance(init_opts, dict) else None+ if not isinstance(fallback_agent, str):+ fallback_agent = ""+ registered_skills = self._infer_legacy_skill_provenance(+ [name for name in registered_skills if isinstance(name, str)],+ pack_id,+ fallback_agent=fallback_agent,+ )+ registered_commands = metadata.get("registered_commands", {}) if metadata else {}+ pack_dir = self.presets_dir / pack_id++ # Record which historical agents this preset's registered_commands+ # actually targeted, *before* any filtering below, so post-removal+ # reconciliation can restore a surviving lower-priority preset's+ # override into every one of those directories too β not only the+ # currently active agent's. Without this, removing a preset that+ # was rendered under a previously-active (now inactive) agent+ # deletes that agent's command file via _unregister_commands below,+ # but active-only reconciliation would only recreate the surviving+ # winner for the current agent, leaving the inactive integration+ # with a missing/stale file (#2948).+ try:+ from ..agents import CommandRegistrar as _CommandRegistrarForScope+ except ImportError:+ _CommandRegistrarForScope = None+ affected_command_agents = {+ agent_name+ for agent_name in registered_commands+ if _CommandRegistrarForScope is None+ or _CommandRegistrarForScope.AGENT_CONFIGS.get(agent_name, {}).get("extension") != "/SKILL.md"+ }++ # Collect ALL command names before filtering for reconciliation,+ # so commands registered only for skill-based agents are also+ # reconciled. Every command-type template's primary name is added+ # unconditionally (not just aliases) since ai_skills-mode presets+ # never populate registered_commands for command-backed+ # integrations (see _register_commands's ai_skills guard) β without+ # this, removing a skills-mode preset that overrides a command no+ # other preset registered "the normal way" would skip reconciliation+ # entirely and _unregister_skills would restore core/extension+ # content instead of a surviving lower-priority preset's override.+ removed_cmd_names = set()+ removed_constitution = any(+ path.exists()+ for path in (+ pack_dir / "templates" / "constitution-template.md",+ pack_dir / "constitution-template.md",+ )+ )+ if metadata and isinstance(metadata.get("version"), str):+ memory_constitution = (+ self.project_root / ".specify" / "memory" / "constitution.md"+ )+ removed_constitution = removed_constitution or (+ _constitution_provenance_matches_preset(+ self.project_root,+ memory_constitution,+ pack_id,+ metadata["version"],+ )+ )+ for cmd_names in registered_commands.values():+ removed_cmd_names.update(cmd_names)+ manifest_path = pack_dir / "preset.yml"+ if manifest_path.exists():+ try:+ manifest = PresetManifest(manifest_path)+ for tmpl in manifest.templates:+ if (+ tmpl.get("type") == "template"+ and tmpl.get("name") == "constitution-template"+ ):+ removed_constitution = True+ if tmpl.get("type") == "command":+ name = tmpl.get("name")+ if isinstance(name, str):+ removed_cmd_names.add(name)+ for alias in tmpl.get("aliases", []):+ if isinstance(alias, str):+ removed_cmd_names.add(alias)+ except PresetValidationError:+ # Invalid manifest β skip alias extraction; primary command+ # names from registered_commands are still unregistered.+ pass++ affected_skill_dirs: Dict[+ Path, tuple[Optional[str], List[str]]+ ] = {}+ if registered_skills:+ restorable_skills = registered_skills+ # A skill tracked for a command-backed agent whose ai_skills is+ # now off is a leftover from a partially failed skillsβcommand+ # toggle. Restoring it via _unregister_skills (and letting+ # _reconcile_skills reapply a surviving lower preset through+ # extra_skills_dirs) would hand the active command-mode agent a+ # skill artifact it must not have β its current representation+ # is the command file handled via registered_commands above.+ # Delete the preset-owned skill instead and keep its directory+ # out of restoration/reconciliation entirely (#2948). Inactive+ # agents' entries still restore as before.+ # The legacy branch above locally imports load_init_options,+ # shadowing the module-level name for this whole function.+ from .._init_options import load_init_options as _load_init_options++ resolved_active = resolve_active_agent_for_registration(+ self.project_root+ )+ if (+ isinstance(registered_skills, dict)+ and isinstance(resolved_active, str)+ and resolved_active in registered_skills+ and _CommandRegistrarForScope is not None+ and _CommandRegistrarForScope.AGENT_CONFIGS.get(+ resolved_active, {}+ ).get("extension") != "/SKILL.md"+ and not is_ai_skills_enabled(+ _load_init_options(self.project_root)+ )+ ):+ raw_names = registered_skills.get(resolved_active)+ stale_names = [+ name+ for name in (+ raw_names if isinstance(raw_names, list) else []+ )+ if isinstance(name, str)+ ]+ restorable_skills = {+ agent_name: names+ for agent_name, names in registered_skills.items()+ if agent_name != resolved_active+ }+ if stale_names:+ self._delete_agent_preset_skills(+ resolved_active, stale_names, pack_id+ )+ override_sources = {+ skill_name: f"override:{command_name}"+ for command_name in removed_cmd_names+ for skill_name in self._skill_names_for_command(command_name)+ }+ affected_skill_dirs = self._unregister_skills(+ restorable_skills,+ pack_dir,+ additional_owned_sources=override_sources,+ restore_from_bundled_core=True,+ )+ try:+ from ..agents import CommandRegistrar+ except ImportError:+ CommandRegistrar = None+ if CommandRegistrar is not None:+ skill_coverage = (+ registered_skills+ if isinstance(registered_skills, dict)+ else {}+ )+ commands_to_unregister: Dict[str, List[str]] = {}+ for agent_name, cmd_names in registered_commands.items():+ is_native_skill_agent = (+ CommandRegistrar.AGENT_CONFIGS.get(+ agent_name, {}+ ).get("extension")+ == "/SKILL.md"+ )+ if not is_native_skill_agent:+ commands_to_unregister[agent_name] = cmd_names+ continue++ raw_skill_names = skill_coverage.get(agent_name, [])+ covered_skill_names = {+ name+ for name in (+ raw_skill_names+ if isinstance(raw_skill_names, list)+ else []+ )+ if isinstance(name, str)+ }+ uncovered_commands = [+ cmd_name+ for cmd_name in cmd_names+ if not isinstance(cmd_name, str)+ or covered_skill_names.isdisjoint(+ self._skill_names_for_command(cmd_name)+ )+ ]+ if uncovered_commands:+ commands_to_unregister[agent_name] = (+ uncovered_commands+ )+ registered_commands = commands_to_unregister++ # Unregister non-skill command files from AI agents.+ if registered_commands:+ self._unregister_commands(registered_commands)++ if pack_dir.exists():+ shutil.rmtree(pack_dir)++ self.registry.remove(pack_id)++ # Reconcile: if other presets still provide these commands,+ # re-resolve from the remaining stack so the next layer takes effect.+ if removed_cmd_names:+ try:+ self._reconcile_composed_commands(+ list(removed_cmd_names), extra_agents=affected_command_agents+ )+ self._reconcile_skills(+ list(removed_cmd_names), extra_skills_dirs=affected_skill_dirs+ )+ except Exception as exc:+ import warnings+ warnings.warn(+ f"Post-removal reconciliation failed for {pack_id}: {exc}. "+ f"Agent command files may be stale; reinstall affected presets "+ f"or run 'specify preset add' to refresh.",+ stacklevel=2,+ )++ if removed_constitution:+ try:+ self._reconcile_constitution()+ except (OSError, UnicodeDecodeError, PresetValidationError, ValueError) as exc:+ import warnings++ warnings.warn(+ f"Post-removal constitution reconciliation failed for {pack_id}: "+ f"{exc}. The live constitution may be stale.",+ stacklevel=2,+ )++ return True++ def list_installed(self) -> List[Dict[str, Any]]:+ """List all installed presets with metadata.++ Returns:+ List of preset metadata dictionaries+ """+ result = []++ for pack_id, metadata in self.registry.list().items():+ # Ensure metadata is a dictionary to avoid AttributeError when using .get()+ if not isinstance(metadata, dict):+ metadata = {}+ pack_dir = self.presets_dir / pack_id+ manifest_path = pack_dir / "preset.yml"++ try:+ manifest = PresetManifest(manifest_path)+ provided_counts = {"commands": 0, "templates": 0, "scripts": 0, "hooks": 0}+ for template in manifest.templates:+ provided_counts[f"{template['type']}s"] += 1+ author = manifest.author+ result.append({+ "id": pack_id,+ "name": manifest.name,+ "version": metadata.get("version", manifest.version),+ "description": manifest.description,+ "enabled": metadata.get("enabled", True),+ "installed_at": metadata.get("installed_at"),+ "template_count": len(manifest.templates),+ "tags": manifest.tags,+ "priority": normalize_priority(metadata.get("priority")),+ "_json_author": author if isinstance(author, str) and author else None,+ "_json_source": metadata.get("source"),+ "_json_provides": provided_counts,+ })+ except PresetValidationError:+ result.append({+ "id": pack_id,+ "name": pack_id,+ "version": metadata.get("version", "unknown"),+ "description": "β οΈ Corrupted preset",+ "enabled": False,+ "installed_at": metadata.get("installed_at"),+ "template_count": 0,+ "tags": [],+ "priority": normalize_priority(metadata.get("priority")),+ "_json_author": None,+ "_json_source": metadata.get("source"),+ "_json_provides": {"commands": 0, "templates": 0, "scripts": 0, "hooks": 0},+ })++ return result++ def get_pack(self, pack_id: str) -> Optional[PresetManifest]:+ """Get manifest for an installed preset.++ Args:+ pack_id: Preset ID++ Returns:+ Preset manifest or None if not installed+ """+ if not self.registry.is_installed(pack_id):+ return None++ pack_dir = self.presets_dir / pack_id+ manifest_path = pack_dir / "preset.yml"++ try:+ return PresetManifest(manifest_path)+ except PresetValidationError:+ return Nonediff --git a/src/specify_cli/presets/_manager_commands.py b/src/specify_cli/presets/_manager_commands.pynew file mode 100644index 000000000..4d665b45d--- /dev/null+++ b/src/specify_cli/presets/_manager_commands.py@@ -0,0 +1,1284 @@+"""Agent command registration and reconciliation for installed presets."""++import copy+from pathlib import Path+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set++if TYPE_CHECKING:+ from ..agents import CommandRegistrar+++from .._init_options import (+ MISSING_INIT_OPTIONS_FILE,+ is_ai_skills_enabled,+ load_init_options,+ resolve_active_agent_for_registration,+)+from ..extensions import ExtensionRegistry+from ._manifest import PresetManifest+from ._resolver import PresetResolver+++def _substitute_core_template(+ body: str,+ cmd_name: str,+ project_root: "Path",+ registrar: "CommandRegistrar",+) -> "tuple[str, dict]":+ """Substitute {CORE_TEMPLATE} with the body of the installed core command template.++ Args:+ body: Preset command body (may contain {CORE_TEMPLATE} placeholder).+ cmd_name: Full command name (e.g. "speckit.git.feature" or "speckit.specify").+ project_root: Project root path.+ registrar: CommandRegistrar instance for parse_frontmatter.++ Returns:+ A tuple of (body, core_frontmatter) where body has {CORE_TEMPLATE} replaced+ by the core template body and core_frontmatter holds the core template's parsed+ frontmatter (so callers can inherit scripts/agent_scripts from it). Both are+ unchanged / empty when the placeholder is absent or the core template file does+ not exist or cannot be read.+ """+ if "{CORE_TEMPLATE}" not in body:+ return body, {}++ # Derive the short name (strip "speckit." prefix) used by core command templates.+ short_name = cmd_name+ if short_name.startswith("speckit."):+ short_name = short_name[len("speckit."):]++ resolver = PresetResolver(project_root)+ # Resolution order for the core template:+ # 1. resolve_core(cmd_name) β covers tier-1 project overrides and tier-3/4+ # name-based lookup (file named <cmd_name>.md). Checked first so that a+ # local override always wins, even for extension commands.+ # 2. resolve_extension_command_via_manifest(cmd_name) β manifest-based tier-3+ # fallback for extension commands whose file is named differently from the+ # command name (e.g. speckit.selftest.extension β commands/selftest.md).+ # 3. resolve_core(short_name) β core template fallback using the unprefixed+ # name (e.g. specify β templates/commands/specify.md).+ # resolve_core() skips installed presets (tier 2) to prevent accidental nesting+ # where another preset's wrap output is mistaken for the real core.+ core_file = (+ resolver.resolve_core(cmd_name, "command")+ or resolver.resolve_extension_command_via_manifest(cmd_name)+ or resolver.resolve_core(short_name, "command")+ )+ if core_file is None:+ return body, {}++ # Treat an unreadable/undecodable core template like a missing one so a+ # single corrupted project override cannot crash command registration β+ # the wrap-strategy callers already skip an unreadable preset source with+ # a warning (CommandRegistrar.register_pack).+ try:+ core_content = core_file.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError) as exc:+ import warnings++ warnings.warn(+ f"Ignoring core template for command '{cmd_name}': could not read "+ f"'{core_file.name}' ({exc.__class__.__name__}: {exc}).",+ stacklevel=2,+ )+ return body, {}++ core_frontmatter, core_body = registrar.parse_frontmatter(core_content)+ return body.replace("{CORE_TEMPLATE}", core_body), core_frontmatter+++class _PresetCommandMethods:+ """Command artifact methods shared through PresetManager's lifecycle state."""++ def _register_commands(+ self,+ manifest: PresetManifest,+ preset_dir: Path+ ) -> Dict[str, List[str]]:+ """Register preset command overrides with all detected AI agents.++ Scans the preset's templates for type "command", reads each command+ file, and writes it to every detected agent directory using the+ CommandRegistrar from the agents module.++ When a command uses a composition strategy (prepend, append, wrap),+ the content is composed with the lower-priority command before+ registration.++ Args:+ manifest: Preset manifest+ preset_dir: Installed preset directory++ Returns:+ Dictionary mapping agent names to lists of registered command names+ """+ command_templates = [+ t for t in manifest.templates if t.get("type") == "command"+ ]+ if not command_templates:+ return {}++ # A preset command template always ships its own body, so it is+ # self-contained and scaffolds regardless of whether any similarly+ # named extension is installed. Namespaced names (speckit.<ns>.<cmd>)+ # are treated exactly like short names (speckit.<cmd>) β they are NOT+ # filtered out just because ``.specify/extensions/<ns>/`` is absent.+ # The only command that cannot be materialized is a composition+ # (prepend/append/wrap) with no base layer to compose onto; that case+ # is handled per-command below (warn + skip), not by dropping names up+ # front.+ # Handle composition strategies: resolve composed content for non-replace commands+ resolver = PresetResolver(self.project_root)+ composed_dir = None+ commands_to_register = []+ for cmd in command_templates:+ strategy = cmd.get("strategy", "replace")+ if strategy != "replace":+ # Only pre-compose if this preset is the top composing layer.+ # If a higher-priority replace already wins, skip composition+ # here β reconciliation will write the correct content.+ layers = resolver.collect_all_layers(cmd["name"], "command")+ top_layer_is_ours = (+ layers and layers[0]["path"].is_relative_to(preset_dir)+ )+ if top_layer_is_ours:+ composed = resolver.resolve_content(cmd["name"], "command")+ if composed is not None:+ if composed_dir is None:+ composed_dir = preset_dir / ".composed"+ composed_dir.mkdir(parents=True, exist_ok=True)+ composed_file = composed_dir / f"{cmd['name']}.md"+ composed_file.write_text(composed, encoding="utf-8")+ commands_to_register.append({+ **cmd,+ "file": f".composed/{cmd['name']}.md",+ })+ else:+ # No base layer to compose onto (e.g. the command it+ # would wrap comes from an extension that isn't+ # installed). Warn and skip this single command rather+ # than aborting the whole install β mirrors the+ # "composed is None" branch in+ # _reconcile_composed_commands so command-mode and+ # reconciliation behave identically.+ import warnings+ warnings.warn(+ f"Command '{cmd['name']}' uses '{strategy}' "+ f"strategy but no base command layer exists to "+ f"compose onto; skipping. Provide a lower-priority "+ f"preset, extension, or core command for it before "+ f"using composition strategies.",+ stacklevel=2,+ )+ continue+ else:+ # Not the top layer β register raw file; reconciliation+ # will overwrite with the correct composed/winning content.+ # Note: CommandRegistrar may process frontmatter strategy: wrap+ # from the raw file (legacy compat), but reconciliation runs+ # immediately after install and corrects the final output.+ commands_to_register.append(cmd)+ else:+ commands_to_register.append(cmd)++ try:+ from ..agents import CommandRegistrar+ except ImportError:+ return {}++ registrar = CommandRegistrar()++ # Single-active rule (#2948): preset command overrides register for+ # the active integration only. A project without a recorded active+ # integration (init-options.json does not exist at all β a legacy+ # pre-init-options layout or direct library use) falls back to+ # detection-based registration for all agents. A recorded key with+ # no registrar config (e.g. "generic") naturally yields no matches+ # via only_agent instead of falling back.+ #+ # An init-options.json that exists but is corrupted, unreadable, or+ # has a malformed/empty "ai" value must not be treated the same as+ # "no file" β that would silently reintroduce all-agent+ # registration. Fail closed (register nothing) instead.+ resolved_agent = resolve_active_agent_for_registration(self.project_root)+ if resolved_agent is MISSING_INIT_OPTIONS_FILE:+ active_agent = None+ elif resolved_agent is None:+ return {}+ else:+ active_agent = resolved_agent+ # Mirror the extension path's ai_skills guard: when the active+ # agent is a command-backed integration (extension != "/SKILL.md")+ # running in skills mode, its preset command overrides render as+ # skills via _register_skills, not as command files. Command-mode+ # and skills-mode artifacts are mutually exclusive β writing both+ # (e.g. `integration use copilot` with `--skills`) leaves a stale+ # command file alongside the SKILL.md that is actually active.+ init_options = load_init_options(self.project_root)+ agent_config = registrar.AGENT_CONFIGS.get(active_agent)+ if (+ agent_config+ and is_ai_skills_enabled(init_options)+ and agent_config.get("extension") != "/SKILL.md"+ ):+ return {}++ return registrar.register_commands_for_all_agents(+ commands_to_register,+ manifest.id,+ preset_dir,+ self.project_root,+ create_missing_active_skills_dir=True,+ only_agent=active_agent,+ )++ def register_enabled_presets_for_agent(self, agent_name: str) -> None:+ """Re-register enabled presets' command overrides and skills for ``agent_name``.++ Mirrors ``ExtensionManager.register_enabled_extensions_for_agent`` for+ presets (#2948): ``integration use`` / ``switch`` call this for the+ newly active agent so a preset installed while a different+ integration was active gets rescaffolded on activation, instead of+ writing artifacts for inactive integrations at install time.+ ``_register_commands`` / ``_register_skills`` already resolve the+ active integration from init-options themselves, so this re-runs them+ for every enabled preset and merges the fresh result for+ ``agent_name`` into its stored registry metadata.++ Presets are processed in *reverse* priority order (lowest-precedence+ first). Each pass overwrites the same target command/skill files, so+ writing the highest-precedence preset last is what makes it win when+ two enabled presets override the same command β matching the+ priority stack documented for ``list_by_priority()``.+ """+ if not agent_name:+ return++ # Resolve once: whether agent_name is a command-backed integration+ # (extension != "/SKILL.md") currently running in skills mode, or+ # vice versa. Native skill-only agents (extension == "/SKILL.md",+ # e.g. claude/codex) have no command/skill toggle at all β both+ # registered_commands and registered_skills legitimately co-exist+ # for them by design, so this restriction only applies to+ # command-backed integrations.+ try:+ from ..agents import CommandRegistrar++ agent_config = CommandRegistrar().AGENT_CONFIGS.get(agent_name)+ except ImportError:+ agent_config = None+ is_command_backed = bool(agent_config) and agent_config.get("extension") != "/SKILL.md"+ ai_skills_now = is_command_backed and is_ai_skills_enabled(+ load_init_options(self.project_root)+ )++ resolver = PresetResolver(self.project_root)+ affected_cmd_names: set = set()+ presets_by_priority = list(self.registry.list_by_priority())+ winning_pack_by_command: Dict[str, str] = {}+ winning_source_by_command: Dict[str, Path] = {}+ project_override_commands: set[str] = set()+ for candidate_pack_id, _candidate_metadata in presets_by_priority:+ candidate_manifest = resolver._get_manifest(+ self.presets_dir / candidate_pack_id+ )+ if candidate_manifest is None:+ continue+ for template in candidate_manifest.templates:+ command_name = template.get("name")+ if (+ template.get("type") == "command"+ and isinstance(command_name, str)+ ):+ if (+ resolver.overrides_dir / f"{command_name}.md"+ ).is_file():+ project_override_commands.add(command_name)+ winning_pack_by_command.setdefault(+ command_name, candidate_pack_id+ )+ source_file = template.get("file")+ if isinstance(source_file, str):+ winning_source_by_command.setdefault(+ command_name,+ self.presets_dir+ / candidate_pack_id+ / source_file,+ )++ pending_command_cleanups: List[+ tuple[+ str,+ Dict[str, List[str]],+ List[str],+ Dict[str, str],+ ]+ ] = []+ successful_skill_replacements: set[tuple[str, str]] = set()+ pending_skill_cleanups: List[+ tuple[+ str,+ Path,+ Dict[str, List[str]],+ List[str],+ Dict[str, str],+ ]+ ] = []+ successful_command_replacements: set[tuple[str, str]] = set()+ for pack_id, metadata in reversed(presets_by_priority):+ pack_dir = self.presets_dir / pack_id+ manifest = resolver._get_manifest(pack_dir)+ if manifest is None:+ continue++ # Registration can write one command and then fail on a later+ # template. Record names first so final reconciliation can repair+ # any partial writes even when _register_commands never returns.+ for tmpl in manifest.templates:+ name = tmpl.get("name")+ if tmpl.get("type") == "command" and isinstance(name, str):+ affected_cmd_names.add(name)++ # Isolate per-preset failures: one preset that fails to register+ # must not abort registration of the remaining enabled presets.+ try:+ registered_commands = self._register_commands(manifest, pack_dir)+ registered_command_names = set(+ registered_commands.get(agent_name) or []+ )+ for tmpl in manifest.templates:+ if tmpl.get("type") != "command":+ continue+ primary_name = tmpl.get("name")+ if (+ isinstance(primary_name, str)+ and primary_name in registered_command_names+ ):+ successful_command_replacements.add(+ (pack_id, primary_name)+ )+ existing_commands = metadata.get("registered_commands", {})+ if not isinstance(existing_commands, dict):+ existing_commands = {}+ merged_commands = copy.deepcopy(existing_commands)+ # Toggled command -> skills for this same agent:+ # _register_commands's ai_skills guard just made this a+ # no-op, but the command file this preset wrote while+ # command mode was active is still on disk and still+ # tracked. Do NOT unregister it yet β _register_skills()+ # below is an independently fallible replacement step, and+ # deleting the old artifact before it succeeds would leave+ # neither the old command file nor a new skill file if+ # skills registration raises. The old artifact is only+ # removed after the skills phase below completes without+ # raising, preserving command/skill mutual exclusion while+ # never leaving a transient failure with nothing in place+ # (#2948).+ stale_command_names: Optional[List[str]] = None+ if registered_commands.get(agent_name):+ existing_names = merged_commands.get(agent_name, [])+ merged_commands[agent_name] = existing_names + [+ name+ for name in registered_commands[agent_name]+ if name not in existing_names+ ]+ elif ai_skills_now and merged_commands.get(agent_name):+ stale_command_names = merged_commands[agent_name]+ # Persist the commands phase immediately, mirroring+ # install_from_directory(): _register_skills is an+ # independently fallible phase, and if it raises, the files+ # the commands phase already wrote to disk must still be+ # tracked so preset removal can clean them up (#2948).+ if merged_commands != existing_commands:+ self.registry.update(pack_id, {"registered_commands": merged_commands})++ registered_skills = self._register_skills(manifest, pack_dir)+ replaced_skill_names = set(registered_skills.get(agent_name) or [])+ for tmpl in manifest.templates:+ if tmpl.get("type") != "command":+ continue+ primary_name = tmpl.get("name")+ if not isinstance(primary_name, str):+ continue+ modern_name, legacy_name = self._skill_names_for_command(+ primary_name+ )+ if (+ modern_name in replaced_skill_names+ or legacy_name in replaced_skill_names+ ):+ successful_skill_replacements.add(+ (pack_id, primary_name)+ )+ raw_existing_skills = metadata.get("registered_skills")+ if isinstance(raw_existing_skills, list) and raw_existing_skills:+ # Legacy flat-list value: don't assume agent_name wrote+ # every name (the first post-upgrade operation may be a+ # direct switch to a different skill-mode agent) β+ # infer real ownership from on-disk provenance instead+ # (#2948).+ existing_skills = self._infer_legacy_skill_provenance(+ [n for n in raw_existing_skills if isinstance(n, str)],+ pack_id,+ fallback_agent=agent_name,+ )+ else:+ existing_skills = self._normalize_registered_skills(+ raw_existing_skills, fallback_agent=agent_name+ )+ merged_skills = copy.deepcopy(existing_skills)+ if registered_skills.get(agent_name):+ existing_names = merged_skills.get(agent_name, [])+ merged_skills[agent_name] = existing_names + [+ name+ for name in registered_skills[agent_name]+ if name not in existing_names+ ]+ elif is_command_backed and not ai_skills_now and merged_skills.get(agent_name):+ # Mirror image: toggled skills -> command for this same+ # agent. _get_skills_dir() no longer resolves a skills+ # directory once ai_skills is off, so _register_skills+ # is a no-op β but the SKILL.md this preset wrote while+ # skills mode was active is still tracked and still on+ # disk. Restore/remove it narrowly for this agent. This+ # direction is already register-new-then-remove-old:+ # _register_commands (the replacement) ran unconditionally+ # above and only reaches here once it has already+ # succeeded β but that call can still have returned+ # empty or partial results (missing source template,+ # safety-validation skip, corrupted manifest), so only+ # retire the subset of stale skills whose corresponding+ # command name was actually returned for this agent;+ # anything unreplaced stays tracked and on disk (#2948).+ stale_skill_names = merged_skills[agent_name]+ skill_to_primary: Dict[str, str] = {}+ for tmpl in manifest.templates:+ if tmpl.get("type") != "command":+ continue+ primary_name = tmpl.get("name")+ if not isinstance(primary_name, str):+ continue+ modern_name, legacy_name = self._skill_names_for_command(+ primary_name+ )+ skill_to_primary[modern_name] = primary_name+ skill_to_primary[legacy_name] = primary_name+ pending_skill_cleanups.append(+ (+ pack_id,+ pack_dir,+ merged_skills,+ stale_skill_names,+ skill_to_primary,+ )+ )+ # A legacy flat-list registered_skills value (predating+ # per-agent provenance) must migrate to the dict format on+ # disk even when the rescaffolded names are unchanged from+ # what the list already held β comparing only the+ # *normalized* forms would otherwise treat that as a no-op+ # and leave the raw un-migrated list in the registry, which+ # later removal/switch handling treats as legacy+ # best-effort (restoring only the currently active agent's+ # directory) instead of per-agent provenance (#2948).+ needs_migration = (+ isinstance(raw_existing_skills, list) and raw_existing_skills+ )+ if merged_skills != existing_skills or needs_migration:+ self.registry.update(pack_id, {"registered_skills": merged_skills})++ # The skills phase above completed without raising, but a+ # non-raising result can still be empty or partial (missing+ # source template, safety-validation skip, corrupted+ # manifest) β retiring every stale command purely on "did+ # not raise" would delete a command whose replacement skill+ # never actually landed, leaving neither artifact. Only+ # retire the subset of stale commands whose corresponding+ # skill name was actually returned for this agent; anything+ # unreplaced stays tracked and on disk (#2948).+ if stale_command_names:+ # Commands may carry aliases (CommandRegistrar.register_+ # commands() tracks and returns primary + alias names+ # flattened together into one list), but _register_+ # skills() only ever renders/returns the *primary*+ # command name's skill β running an alias's own name+ # through _skill_names_for_command() never matches+ # anything real, so an alias would stay tracked/on-disk+ # forever even after its primary's skill replacement+ # landed. Map each stale name back to its template's+ # primary via the manifest so the whole primary+alias+ # group is retired or kept together, based solely on+ # whether the *primary*'s skill replacement actually+ # landed (#2948).+ alias_to_primary: Dict[str, str] = {}+ for tmpl in manifest.templates:+ if tmpl.get("type") != "command":+ continue+ primary_name = tmpl.get("name")+ if not isinstance(primary_name, str):+ continue+ for alias in tmpl.get("aliases", []):+ if isinstance(alias, str):+ alias_to_primary[alias] = primary_name++ pending_command_cleanups.append(+ (+ pack_id,+ merged_commands,+ stale_command_names,+ alias_to_primary,+ )+ )+ except Exception as pack_err:+ from .. import _print_cli_warning++ _print_cli_warning(+ "register preset artifacts for",+ "preset",+ pack_id,+ pack_err,+ continuing="Continuing with the remaining presets.",+ )+ continue++ # Registration writes each preset's raw layer. Reconcile before+ # retiring opposite-mode artifacts so project overrides and composed+ # winners are materialized first, and so cleanup runs last instead of+ # being undone by skill reconciliation.+ reconciled_commands: set[str] = set()+ reconciled_skills: set[str] = set()+ if affected_cmd_names:+ try:+ reconciled_commands = self._reconcile_composed_commands(+ list(affected_cmd_names), target_agent=agent_name+ )+ reconciled_skills = self._reconcile_skills(+ list(affected_cmd_names), target_agent=agent_name+ )+ except Exception as exc:+ import warnings++ warnings.warn(+ f"Post-rescaffold reconciliation failed for '{agent_name}': "+ f"{exc}. Agent command files may be stale; re-run "+ f"'specify integration use {agent_name}' or reinstall "+ f"affected presets to refresh.",+ stacklevel=2,+ )++ successfully_replaced_winners = {+ command_name+ for command_name, winning_pack_id in winning_pack_by_command.items()+ if command_name not in project_override_commands+ and (+ (winning_pack_id, command_name)+ in successful_skill_replacements+ or (+ command_name in reconciled_skills+ and command_name in winning_source_by_command+ and winning_source_by_command[command_name].is_file()+ )+ )+ }+ successfully_replaced_winners.update(+ project_override_commands & reconciled_skills+ )++ for (+ pack_id,+ merged_commands,+ stale_command_names,+ alias_to_primary,+ ) in pending_command_cleanups:+ fully_replaced = [+ command_name+ for command_name in stale_command_names+ if alias_to_primary.get(command_name, command_name)+ in successfully_replaced_winners+ ]+ if not fully_replaced:+ continue+ remaining_stale = [+ command_name+ for command_name in stale_command_names+ if command_name not in fully_replaced+ ]+ self._unregister_commands({agent_name: fully_replaced})+ if remaining_stale:+ merged_commands[agent_name] = remaining_stale+ else:+ merged_commands.pop(agent_name, None)+ self.registry.update(+ pack_id, {"registered_commands": merged_commands}+ )++ successfully_replaced_command_winners = {+ command_name+ for command_name, winning_pack_id in winning_pack_by_command.items()+ if command_name not in project_override_commands+ and (+ (winning_pack_id, command_name)+ in successful_command_replacements+ or (+ command_name in reconciled_commands+ and command_name in winning_source_by_command+ and winning_source_by_command[command_name].is_file()+ )+ )+ }+ successfully_replaced_command_winners.update(+ project_override_commands & reconciled_commands+ )++ # Skill restoration walks the priority stack, so retire stale layers+ # from highest to lowest. The last cleanup then restores the true+ # non-preset fallback (or removes the skill) rather than cycling back+ # to a lower-priority preset.+ for (+ pack_id,+ pack_dir,+ merged_skills,+ stale_skill_names,+ skill_to_primary,+ ) in reversed(pending_skill_cleanups):+ fully_replaced = [+ skill_name+ for skill_name in stale_skill_names+ if skill_to_primary.get(skill_name)+ in successfully_replaced_command_winners+ ]+ if not fully_replaced:+ continue+ remaining_stale = [+ skill_name+ for skill_name in stale_skill_names+ if skill_name not in fully_replaced+ ]+ override_sources = {+ skill_name: f"override:{skill_to_primary[skill_name]}"+ for skill_name in fully_replaced+ if skill_name in skill_to_primary+ }+ self._unregister_skills(+ {agent_name: fully_replaced},+ pack_dir,+ additional_owned_sources=override_sources,+ )+ if remaining_stale:+ merged_skills[agent_name] = remaining_stale+ else:+ merged_skills.pop(agent_name, None)+ self.registry.update(+ pack_id, {"registered_skills": merged_skills}+ )++ def unregister_agent_artifacts(self, agent_name: str) -> None:+ """Remove ``agent_name``'s tracked preset command/skill artifacts.++ Mirrors ``ExtensionManager.unregister_agent_artifacts()`` (#2948):+ used by ``integration switch`` when deactivating the previous+ integration, so a preset's command overrides and skill mirrors+ written for that agent don't linger as orphans in its directory+ once a different (possibly not-yet-installed) integration becomes+ active β including custom preset commands and files the registrar+ would otherwise skip as user-modified.++ Scoped strictly to ``agent_name``: only that agent's own tracked+ artifacts and registry entries are touched. Other agents' files,+ tracking, and preset packs themselves are left untouched, and no+ priority-stack reconciliation runs β this is agent-scoped cleanup+ only, not preset removal.+ """+ if not agent_name:+ return++ try:+ from ..agents import CommandRegistrar++ registrar = CommandRegistrar()+ agent_config = registrar.AGENT_CONFIGS.get(agent_name)+ except ImportError:+ registrar = None+ agent_config = None+ if agent_config is None or registrar is None:+ return++ for pack_id, metadata in list(self.registry.list().items()):+ updates: Dict[str, Any] = {}++ raw_skills = metadata.get("registered_skills", [])+ if isinstance(raw_skills, list) and raw_skills:+ # Legacy flat-list value predating per-agent provenance:+ # infer real ownership from on-disk markers before removing+ # anything, so only agent_name's actual share is unregistered+ # and the rest migrates to per-agent form instead of either+ # guessing every name belongs to agent_name or blindly+ # leaving other agents' shares unrecoverable (#2948).+ registered_skills_all = self._infer_legacy_skill_provenance(+ [n for n in raw_skills if isinstance(n, str)],+ pack_id,+ fallback_agent=agent_name,+ )+ skills_migrated = True+ elif isinstance(raw_skills, dict):+ registered_skills_all = copy.deepcopy(raw_skills)+ skills_migrated = False+ else:+ registered_skills_all = {}+ skills_migrated = False++ registered_commands = metadata.get("registered_commands", {})+ if not isinstance(registered_commands, dict):+ registered_commands = {}++ agent_command_names = [+ n for n in registered_commands.get(agent_name, []) if isinstance(n, str)+ ]++ # Native SKILL.md agents (claude/codex/agy/β¦) materialize their+ # preset override in _register_commands(), tracked under+ # registered_commands, not registered_skills β see+ # _register_skills()'s own docstring ("Native skill agents β¦+ # materialize brand-new preset skills in _register_commands()").+ # A legacy flat-list registered_skills value predating that+ # split can still attribute the very same on-disk file to this+ # agent via provenance inference; unregistering through both+ # paths would double-process the identical directory (delete+ # via the commands path, then no-op "restore" via the skills+ # path since the directory is already gone). Mirror remove()'s+ # own coordination: whenever this agent's artifact is already+ # handled via registered_commands, never additionally treat it+ # as a registered_skills entry for the same agent.+ native_skills_entry_removed = False+ if agent_command_names and agent_config.get("extension") == "/SKILL.md":+ native_skills_entry_removed = agent_name in registered_skills_all+ registered_skills_all.pop(agent_name, None)++ if agent_command_names:+ command_names_to_unregister = agent_command_names+ if agent_config.get("extension") == "/SKILL.md":+ agent_output = registrar._resolve_agent_dir(+ agent_name, agent_config, self.project_root+ )+ shared_names: set[str] = set()+ for other_agent, other_names in registered_commands.items():+ if (+ other_agent == agent_name+ or not isinstance(other_names, list)+ ):+ continue+ other_config = registrar.AGENT_CONFIGS.get(other_agent)+ if (+ not other_config+ or other_config.get("extension") != "/SKILL.md"+ ):+ continue+ other_output = registrar._resolve_agent_dir(+ other_agent, other_config, self.project_root+ )+ if other_output == agent_output:+ shared_names.update(+ name+ for name in other_names+ if isinstance(name, str)+ )+ command_names_to_unregister = [+ name+ for name in agent_command_names+ if name not in shared_names+ ]+ if command_names_to_unregister:+ self._unregister_commands(+ {agent_name: command_names_to_unregister}+ )+ new_registered_commands = copy.deepcopy(registered_commands)+ new_registered_commands.pop(agent_name, None)+ updates["registered_commands"] = new_registered_commands++ agent_skill_names = registered_skills_all.get(agent_name) or []+ if (+ agent_skill_names+ or skills_migrated+ or native_skills_entry_removed+ ):+ if agent_skill_names:+ self._delete_agent_preset_skills(+ agent_name, agent_skill_names, pack_id+ )+ remaining = {+ other_agent: names+ for other_agent, names in registered_skills_all.items()+ if other_agent != agent_name+ }+ updates["registered_skills"] = remaining++ if updates:+ self.registry.update(pack_id, updates)++ def _unregister_commands(self, registered_commands: Dict[str, List[str]]) -> None:+ """Remove previously registered command files from agent directories.++ Args:+ registered_commands: Dict mapping agent names to command name lists+ """+ try:+ from ..agents import CommandRegistrar+ except ImportError:+ return++ registrar = CommandRegistrar()+ registrar.unregister_commands(registered_commands, self.project_root)++ def _merge_pack_registered_commands(+ self, pack_id: str, written: Optional[Dict[str, List[str]]]+ ) -> None:+ """Merge actually-written agent command registrations into a preset's metadata.++ Reconciliation (``_reconcile_composed_commands``) can write a+ preset's content into an agent directory the preset never wrote to+ before β most notably a historical (currently inactive) agent+ supplied via ``extra_agents`` when a higher-priority preset is+ removed. If that write isn't reflected back into the winning+ preset's own ``registered_commands``, the registry silently lies+ about which directories the preset owns: a later removal of this+ same preset only cleans up the agents it already knew about,+ orphaning the directory reconciliation just wrote to on its behalf+ (#2948).++ Args:+ pack_id: The preset whose metadata should be updated.+ written: ``{agent_name: [cmd_name, ...]}`` actually written by+ the reconciliation call just made, exactly mirroring+ ``CommandRegistrar.register_commands_for_non_skill_agents``'s+ return value. A falsy value is a no-op.+ """+ if not written:+ return+ metadata = self.registry.get(pack_id)+ if metadata is None:+ return # pack_id no longer installed (e.g. removed mid-loop)+ existing_commands = metadata.get("registered_commands", {})+ if not isinstance(existing_commands, dict):+ existing_commands = {}+ merged_commands = copy.deepcopy(existing_commands)+ changed = False+ for agent_name, cmd_names in written.items():+ if not cmd_names:+ continue+ existing_names = merged_commands.get(agent_name, [])+ new_names = [n for n in cmd_names if n not in existing_names]+ if new_names:+ merged_commands[agent_name] = existing_names + new_names+ changed = True+ if changed:+ self.registry.update(pack_id, {"registered_commands": merged_commands})++ def _merge_extension_registered_commands(+ self, extension_id: str, written: Optional[Dict[str, List[str]]]+ ) -> None:+ """Merge reconciliation writes into an extension's registry entry."""+ if not written:+ return+ registry = ExtensionRegistry(self.project_root / ".specify" / "extensions")+ metadata = registry.get(extension_id)+ if metadata is None:+ return+ existing_commands = metadata.get("registered_commands", {})+ if not isinstance(existing_commands, dict):+ existing_commands = {}+ merged_commands = copy.deepcopy(existing_commands)+ changed = False+ for agent_name, cmd_names in written.items():+ existing_names = merged_commands.get(agent_name, [])+ new_names = [name for name in cmd_names if name not in existing_names]+ if new_names:+ merged_commands[agent_name] = existing_names + new_names+ changed = True+ if changed:+ registry.update(extension_id, {"registered_commands": merged_commands})++ def _reconcile_composed_commands(+ self,+ command_names: List[str],+ extra_agents: Optional[Set[str]] = None,+ target_agent: Optional[str] = None,+ ) -> Set[str]:+ """Re-resolve and re-register composed commands from the full stack.++ After install or remove, recompute the effective content for each+ command name that participates in composition, and write the winning+ content to the agent directories. This ensures command files always+ reflect the current priority stack rather than depending on+ install/remove order.++ Single-active rule (#2948): non-skill command-file registration+ performed by this pass is restricted to the active integration, the+ same as ``_register_commands``. Without this, reconciliation after+ install/remove would write command files for every detected+ non-skill agent even though registration itself is active-only,+ leaving inactive integrations with artifacts that are never+ recorded in ``registered_commands`` (and therefore never cleaned up+ on removal).++ Args:+ command_names: List of command names to reconcile+ extra_agents: Additional agent names to also reconcile besides+ the currently active one. Populated by ``remove()`` with the+ historical agents a just-removed preset's+ ``registered_commands`` actually targeted, so a surviving+ lower-priority preset's content is restored there too β not+ only for the currently active agent (#2948). Install/use+ callers omit this, preserving pure active-only behavior.+ target_agent: If set, report only command names written for this+ agent. Other callers receive the union of all written names.++ Returns:+ Command names successfully written by this reconciliation pass.+ """+ if not command_names:+ return set()++ # Every preset-owned command name flows through unchanged. Names are+ # NOT filtered by the ``speckit.<ns>.<cmd>`` shape: a self-contained+ # preset command scaffolds whether or not a like-named extension is+ # installed (parity with _register_commands), and a name whose base+ # layer has disappeared must still reach the loop below so its now+ # uncomposable stale file gets unregistered. The loop already skips+ # names that resolve to no layers at all (``if not layers: continue``).+ try:+ from ..agents import CommandRegistrar+ except ImportError:+ return set()++ resolver = PresetResolver(self.project_root)+ registrar = CommandRegistrar()+ reconciled_commands: set[str] = set()++ def record_written(written: Dict[str, List[str]]) -> None:+ if target_agent is not None:+ reconciled_commands.update(written.get(target_agent, []))+ else:+ for names in written.values():+ reconciled_commands.update(names)++ # Resolve the active-only restriction once. MISSING_INIT_OPTIONS_FILE+ # (legacy pre-init-options project) keeps the pre-#2948 fallback of+ # registering every detected non-skill agent; a corrupted/malformed+ # init-options.json fails closed via a sentinel that matches no real+ # agent name instead of silently falling back to "no restriction".+ resolved_agent = resolve_active_agent_for_registration(self.project_root)+ if resolved_agent is MISSING_INIT_OPTIONS_FILE:+ only_agent: Optional[str] = None+ elif resolved_agent is None:+ only_agent = ""+ else:+ only_agent = resolved_agent+ # Mirror _register_commands's ai_skills guard: a command-backed+ # active agent running in skills mode renders preset/extension+ # overrides as skills, not command files, so this non-skill+ # command reconciliation pass must not target it either.+ agent_config = registrar.AGENT_CONFIGS.get(only_agent)+ if (+ agent_config+ and is_ai_skills_enabled(load_init_options(self.project_root))+ and agent_config.get("extension") != "/SKILL.md"+ ):+ only_agent = ""++ # The active agent's participation is decided exclusively by the+ # only_agent guard above (which encodes the ai_skills mode). A+ # partially failed commandβskills toggle can leave the active agent+ # behind in extra_agents via its stale registered_commands entry,+ # and register_commands_for_non_skill_agents admits every+ # extra_agents member even when only_agent excludes the agent β+ # recreating a command file for an agent now running in skills+ # mode. Never re-admit the active agent through the+ # historical-agents side channel (#2948).+ if extra_agents and isinstance(resolved_agent, str):+ extra_agents = set(extra_agents) - {resolved_agent}++ # Cache registry and manifests outside the loop to avoid+ # repeated filesystem reads for each command name.+ presets_by_priority = list(self.registry.list_by_priority())++ for cmd_name in command_names:+ layers = resolver.collect_all_layers(cmd_name, "command")+ if not layers:+ continue++ # If the top layer is replace, it wins entirely β lower layers+ # are irrelevant regardless of their strategies.+ top_is_replace = layers[0]["strategy"] == "replace"+ has_composition = not top_is_replace and any(+ layer["strategy"] != "replace" for layer in layers+ )+ if not has_composition:+ # Pure replace β the top layer wins.+ top_layer = layers[0]+ top_path = top_layer["path"]+ # Try to find which preset owns this layer+ registered = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ if top_path.is_relative_to(pack_dir):+ manifest = resolver._get_manifest(pack_dir)+ if manifest:+ for tmpl in manifest.templates:+ if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":+ written = self._register_for_non_skill_agents(+ registrar, [tmpl], manifest.id, pack_dir,+ only_agent=only_agent, extra_agents=extra_agents,+ )+ record_written(written)+ self._merge_pack_registered_commands(manifest.id, written)+ registered = True+ break+ break+ if not registered:+ # Top layer is a non-preset source (extension, core, or+ # project override). Register directly from the layer path.+ source = layers[0]["source"]+ extension_id = None+ written: Dict[str, List[str]] = {}+ if source.startswith("extension:"):+ # Use extension's own registration to preserve context formatting+ extension_id = source.split(":", 1)[1].split(" ", 1)[0]+ ext_dir = (+ self.project_root / ".specify" / "extensions" / extension_id+ )+ ext_manifest_path = ext_dir / "extension.yml"+ if ext_manifest_path.exists():+ try:+ from ..extensions import ExtensionManifest+ ext_manifest = ExtensionManifest(ext_manifest_path)+ # Filter to only the command being reconciled+ matching_cmds = [+ c for c in ext_manifest.commands+ if c.get("name") == cmd_name+ ]+ if matching_cmds:+ written = registrar.register_commands_for_non_skill_agents(+ matching_cmds, extension_id, ext_dir,+ self.project_root,+ context_note=f"\n<!-- Extension: {extension_id} -->\n<!-- Config: .specify/extensions/{extension_id}/ -->\n",+ extension_id=extension_id,+ only_agent=only_agent,+ extra_agents=extra_agents,+ )+ record_written(written)+ registered = True+ except (ImportError, FileNotFoundError, OSError):+ # Extension registration failed; fall back to+ # generic path-based registration below.+ pass+ if not registered:+ source_id = extension_id or source+ written = self._register_command_from_path(+ registrar, cmd_name, top_path,+ source_id=source_id,+ only_agent=only_agent, extra_agents=extra_agents,+ )+ record_written(written)+ if extension_id:+ self._merge_extension_registered_commands(+ extension_id, written+ )+ else:+ # Composed command β resolve from full stack+ composed = resolver.resolve_content(cmd_name, "command")+ if composed is None:+ # Composition no longer possible (e.g. base layer removed).+ # Unregister any stale command file from non-skill agents.+ import warnings+ warnings.warn(+ f"Cannot compose command '{cmd_name}': no base layer. "+ f"Stale command files may remain.",+ stacklevel=2,+ )+ registrar._ensure_configs()+ # Include aliases from the top layer's manifest+ cmd_names_to_unregister = [cmd_name]+ for _pid, _meta in presets_by_priority:+ _pd = self.presets_dir / _pid+ _m = resolver._get_manifest(_pd)+ if _m:+ for _t in _m.templates:+ if _t.get("name") == cmd_name and _t.get("type") == "command":+ for alias in _t.get("aliases", []):+ if isinstance(alias, str):+ cmd_names_to_unregister.append(alias)+ break+ # Mirror the active-only restriction used elsewhere in+ # this pass: without it, unregistering a stale composed+ # command would touch every non-skill agent's directory,+ # deleting historical artifacts from integrations that+ # were never active when this preset registered (#2948).+ registrar.unregister_commands(+ {+ agent: cmd_names_to_unregister+ for agent in registrar.AGENT_CONFIGS+ if registrar.AGENT_CONFIGS[agent].get("extension") != "/SKILL.md"+ and (+ only_agent is None+ or agent == only_agent+ or agent in (extra_agents or ())+ )+ },+ self.project_root,+ )+ continue++ # Write to the highest-priority preset's .composed dir+ registered = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ manifest = resolver._get_manifest(pack_dir)+ if not manifest:+ continue+ for tmpl in manifest.templates:+ if tmpl.get("name") == cmd_name and tmpl.get("type") == "command":+ composed_dir = pack_dir / ".composed"+ composed_dir.mkdir(parents=True, exist_ok=True)+ composed_file = composed_dir / f"{cmd_name}.md"+ composed_file.write_text(composed, encoding="utf-8")+ written = self._register_for_non_skill_agents(+ registrar,+ [{**tmpl, "file": f".composed/{cmd_name}.md"}],+ manifest.id, pack_dir,+ only_agent=only_agent, extra_agents=extra_agents,+ )+ record_written(written)+ self._merge_pack_registered_commands(manifest.id, written)+ registered = True+ break+ else:+ continue+ break+ if not registered:+ # No preset owns this composed command β write to a+ # shared .composed dir and register from the top layer.+ shared_composed = self.presets_dir / ".composed"+ shared_composed.mkdir(parents=True, exist_ok=True)+ composed_file = shared_composed / f"{cmd_name}.md"+ composed_file.write_text(composed, encoding="utf-8")+ source = layers[0]["source"]+ if source.startswith("extension:"):+ source_id = source.split(":", 1)[1].split(" ", 1)[0]+ else:+ source_id = source+ written = self._register_command_from_path(+ registrar, cmd_name, composed_file,+ source_id=source_id,+ only_agent=only_agent, extra_agents=extra_agents,+ )+ record_written(written)+ if source.startswith("extension:"):+ self._merge_extension_registered_commands(+ source_id, written+ )++ return reconciled_commands++ def _register_command_from_path(+ self,+ registrar: Any,+ cmd_name: str,+ cmd_path: Path,+ source_id: str = "reconciled",+ only_agent: Optional[str] = None,+ extra_agents: Optional[Set[str]] = None,+ ) -> Dict[str, List[str]]:+ """Register a single command from a file path (non-preset source).++ Used by reconciliation when the winning layer is an extension,+ core template, or project override rather than a preset.++ Args:+ registrar: CommandRegistrar instance+ cmd_name: Command name+ cmd_path: Path to the command file+ source_id: Source attribution for rendered output+ only_agent: If set, restrict registration to this single agent (#2948).+ extra_agents: Additional agent names to register for besides+ ``only_agent`` (post-removal reconciliation only, #2948).++ Returns:+ ``{agent_name: [cmd_name, ...]}`` for every agent this call+ actually registered the command for (empty if the source path+ doesn't exist or nothing was written).+ """+ if not cmd_path.exists():+ return {}+ cmd_tmpl: Dict[str, Any] = {+ "name": cmd_name,+ "type": "command",+ "file": cmd_path.name,+ }+ # Load aliases from extension manifest when the winning layer is an extension+ if source_id and not source_id.startswith("preset:"):+ try:+ from ..extensions import ExtensionManifest+ for ext_dir in (self.project_root / ".specify" / "extensions").iterdir():+ if not ext_dir.is_dir():+ continue+ if cmd_path.is_relative_to(ext_dir):+ manifest_path = ext_dir / "extension.yml"+ if manifest_path.exists():+ ext_manifest = ExtensionManifest(manifest_path)+ for cmd in ext_manifest.commands:+ if cmd.get("name") == cmd_name:+ aliases = cmd.get("aliases", [])+ if isinstance(aliases, list) and aliases:+ cmd_tmpl["aliases"] = aliases+ break+ break+ except Exception:+ pass # best-effort alias loading+ return self._register_for_non_skill_agents(+ registrar, [cmd_tmpl], source_id, cmd_path.parent,+ only_agent=only_agent, extra_agents=extra_agents,+ )++ def _register_for_non_skill_agents(+ self,+ registrar: Any,+ commands: List[Dict[str, Any]],+ source_id: str,+ source_dir: Path,+ only_agent: Optional[str] = None,+ extra_agents: Optional[Set[str]] = None,+ ) -> Dict[str, List[str]]:+ """Register commands for non-skill agents during reconciliation.++ Skill-based agents (``/SKILL.md`` layout) are handled separately:+ - On removal: ``_unregister_skills()`` restores from core/extension,+ then ``_reconcile_skills()`` re-runs ``_register_skills()`` for the+ next winning preset so SKILL.md files get proper frontmatter and+ descriptions.+ - On install: ``_register_skills()`` writes formatted SKILL.md, then+ ``_reconcile_skills()`` ensures the actual priority winner is used.++ Writing raw command content to skill agents would produce invalid+ SKILL.md files (missing skill frontmatter, descriptions, etc.).++ Args:+ only_agent: If set, restrict registration to this single agent,+ matching the active-only rule applied by ``_register_commands``+ (#2948).+ extra_agents: Additional agent names to register for besides+ ``only_agent``. Used by post-removal reconciliation to also+ restore surviving content into historical agent directories+ a just-removed preset actually wrote to (#2948).++ Returns:+ ``{agent_name: [cmd_name, ...]}`` for every agent this call+ actually registered a command for, mirroring+ ``CommandRegistrar.register_commands_for_non_skill_agents``'s+ return value so callers can merge it into a preset's own+ ``registered_commands`` tracking (#2948).+ """+ return registrar.register_commands_for_non_skill_agents(+ commands, source_id, source_dir, self.project_root,+ only_agent=only_agent, extra_agents=extra_agents,+ )diff --git a/src/specify_cli/presets/_manager_skills.py b/src/specify_cli/presets/_manager_skills.pynew file mode 100644index 000000000..fa7e715a3--- /dev/null+++ b/src/specify_cli/presets/_manager_skills.py@@ -0,0 +1,1544 @@+"""Agent skill registration and safe reconciliation for installed presets."""++import copy+import os+import shutil+from pathlib import Path+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Union++if TYPE_CHECKING:+ from ..agents import CommandRegistrar+++from .._init_options import is_ai_skills_enabled+from .._invocation_style import get_invocation_prefix+from .._utils import dump_frontmatter+from ..integrations.base import IntegrationBase+from ._manager_commands import _substitute_core_template+from ._manifest import PresetManifest, PresetValidationError+from ._resolver import PresetResolver+++class _PresetSkillMethods:+ """Skill artifact methods shared through PresetManager's lifecycle state."""++ class _FilteredManifest:+ """Wrapper that exposes only selected command templates from a manifest.++ Used by _reconcile_skills to avoid overwriting skills for commands+ that aren't being reconciled.+ """++ def __init__(self, manifest: "PresetManifest", cmd_names: set):+ self._manifest = manifest+ self._cmd_names = cmd_names++ def __getattr__(self, name: str):+ return getattr(self._manifest, name)++ @property+ def templates(self) -> List[Dict[str, Any]]:+ return [+ t for t in self._manifest.templates+ if t.get("name") in self._cmd_names+ ]++ def _merge_pack_registered_skills(+ self, pack_id: str, written: Optional[Dict[str, List[str]]]+ ) -> None:+ """Merge actually-written agent skill registrations into a preset's metadata.++ Mirrors :meth:`_merge_pack_registered_commands` for the skills+ side: ``_reconcile_skills`` can render a preset's SKILL.md content+ into an agent directory the preset never wrote to before β most+ notably a historical (currently inactive) agent restored via+ ``extra_skills_dirs`` when a higher-priority preset is removed. If+ that write isn't reflected back into the winning preset's own+ ``registered_skills``, a later removal of this same preset only+ cleans up the agents it already knew about, orphaning the skill+ directory reconciliation just wrote to on its behalf (#2948).++ Args:+ pack_id: The preset whose metadata should be updated.+ written: ``{agent_name: [skill_name, ...]}`` actually written+ by the ``_register_skills`` call just made. A falsy value+ is a no-op.+ """+ if not written:+ return+ metadata = self.registry.get(pack_id)+ if metadata is None:+ return # pack_id no longer installed (e.g. removed mid-loop)+ raw_existing_skills = metadata.get("registered_skills")+ if isinstance(raw_existing_skills, list) and raw_existing_skills:+ # Legacy flat-list value: infer real per-agent ownership from+ # on-disk provenance rather than guessing (#2948).+ fallback_agent = next(iter(written)) if written else None+ existing_skills = self._infer_legacy_skill_provenance(+ [n for n in raw_existing_skills if isinstance(n, str)],+ pack_id,+ fallback_agent=fallback_agent,+ )+ else:+ existing_skills = self._normalize_registered_skills(raw_existing_skills)+ merged_skills = copy.deepcopy(existing_skills)+ changed = (+ isinstance(raw_existing_skills, list) and bool(raw_existing_skills)+ )+ for agent_name, skill_names in written.items():+ if not skill_names:+ continue+ existing_names = merged_skills.get(agent_name, [])+ new_names = [n for n in skill_names if n not in existing_names]+ if new_names:+ merged_skills[agent_name] = existing_names + new_names+ changed = True+ if changed:+ self.registry.update(pack_id, {"registered_skills": merged_skills})++ def _reconcile_skills(+ self,+ command_names: List[str],+ extra_skills_dirs: Optional[+ Dict[Path, tuple[Optional[str], List[str]]]+ ] = None,+ target_agent: Optional[str] = None,+ ) -> Set[str]:+ """Re-register skills for commands whose winning layer changed.++ After a preset is removed, finds the next preset in the priority+ stack that provides each command and re-runs skill registration+ for that preset so SKILL.md files reflect the current winner.++ Args:+ command_names: List of command names to reconcile skills for+ extra_skills_dirs: Additional+ ``{skills_dir: (renderer_agent, managed_skill_names)}``+ entries restored by ``_unregister_skills``. Reconciliation+ is limited to the names actually managed in each directory.+ target_agent: If set, report only command names written for this+ agent. Other callers receive the union of all written names.++ Returns:+ Command names whose skill output was successfully written.+ """+ if not command_names:+ return set()++ # Preset-owned command names are not filtered by the+ # ``speckit.<ns>.<cmd>`` shape here either: a self-contained preset+ # command renders its skill whether or not a like-named extension is+ # installed. The per-name loop below skips anything that doesn't+ # resolve to a managed skill directory.+ resolver = PresetResolver(self.project_root)+ active_skills_dir = self._get_skills_dir()++ from .. import load_init_options++ init_opts = load_init_options(self.project_root)+ active_ai = init_opts.get("ai") if isinstance(init_opts, dict) else None+ if not isinstance(active_ai, str) or not active_ai:+ active_ai = None++ # Cache registry once to avoid repeated filesystem reads+ presets_by_priority = list(self.registry.list_by_priority())++ # Group command names by winning preset to batch _register_skills calls+ # while only registering skills for the specific commands being+ # reconciled. This resolution (which preset/content wins) is+ # directory-independent, so it's computed once and then applied to+ # every affected directory below.+ preset_cmds: Dict[str, List[str]] = {}+ non_preset_skills: List[tuple] = []+ managed_skill_names: set = set()+ reconciled_skill_commands: set[str] = set()++ for cmd_name in command_names:+ layers = resolver.collect_all_layers(cmd_name, "command")+ if not layers:+ continue++ skill_name, legacy_skill_name = self._skill_names_for_command(+ cmd_name+ )+ candidate_skill_names = {skill_name, legacy_skill_name}+ # Track whether any preset previously registered this skill+ # (i.e., it was actively managed), so a not-yet-existing skill+ # dir can be re-created per affected directory below.+ for _pid, meta in presets_by_priority:+ if not isinstance(meta, dict):+ continue+ recorded = meta.get("registered_skills", [])+ if isinstance(recorded, dict):+ recorded_names = {+ name+ for names in recorded.values()+ if isinstance(names, list)+ for name in names+ }+ elif isinstance(recorded, list):+ recorded_names = set(recorded)+ else:+ recorded_names = set()+ recorded_candidates = (+ candidate_skill_names & recorded_names+ )+ if recorded_candidates:+ managed_skill_names.update(recorded_candidates)++ top_path = layers[0]["path"]+ # Find the preset that owns the winning layer+ found_preset = False+ for pack_id, _meta in presets_by_priority:+ pack_dir = self.presets_dir / pack_id+ if top_path.is_relative_to(pack_dir):+ preset_cmds.setdefault(pack_id, []).append(cmd_name)+ found_preset = True+ break+ if not found_preset:+ # Winner is a non-preset source (core/extension/override).+ # Track the winning layer path for skill restoration.+ non_preset_skills.append((skill_name, cmd_name, layers[0]))++ core_ext_skills = [s for s in non_preset_skills if s[2]["source"] != "project override"]+ override_skills = [s for s in non_preset_skills if s[2]["source"] == "project override"]++ def apply_to_dir(+ skills_dir: Path,+ dir_agent: Optional[str],+ *,+ is_active: bool,+ managed_names: Optional[Set[str]] = None,+ ) -> None:+ dir_managed_names = (+ managed_skill_names if managed_names is None else managed_names+ )+ # Restore skills for commands whose winner is non-preset.+ # _unregister_skills_in_dir can rmtree the skill dir, so+ # overrides must be handled directly (create dir + write)+ # without that call.+ dir_core_ext_names = [+ candidate+ for _skill_name, cmd_name, _top_layer in core_ext_skills+ for candidate in self._skill_names_for_command(cmd_name)+ if candidate in dir_managed_names+ ]+ if dir_core_ext_names:+ self._unregister_skills_in_dir(+ dir_core_ext_names,+ skills_dir,+ dir_agent,+ restore_from_bundled_core=True,+ )++ for _skill_name, cmd_name, top_layer in override_skills:+ target_skill_names = [+ name+ for name in self._skill_names_for_command(cmd_name)+ if name in dir_managed_names+ ]+ if not target_skill_names:+ continue+ try:+ from .. import SKILL_DESCRIPTIONS+ from ..agents import CommandRegistrar+ from ..shared_infra import _write_shared_text+ registrar = CommandRegistrar()+ content = top_layer["path"].read_text(encoding="utf-8")+ fm, body = registrar.parse_frontmatter(content)+ short_name = cmd_name+ if short_name.startswith("speckit."):+ short_name = short_name[len("speckit."):]+ desc = fm.get("description", "") or SKILL_DESCRIPTIONS.get(+ short_name.replace(".", "-"),+ f"Command: {short_name}",+ )+ selected_ai = dir_agent if isinstance(dir_agent, str) else ""+ if selected_ai:+ body = registrar.resolve_skill_placeholders(+ selected_ai, fm, body, self.project_root+ )+ body = self._resolve_skill_command_refs(+ body, registrar, selected_ai, self.project_root+ )+ from ..integrations import get_integration+ integration = get_integration(selected_ai) if selected_ai else None+ skill_title = self._skill_title_from_command(cmd_name)+ wrote_override = False+ for target_skill_name in target_skill_names:+ skill_subdir = skills_dir / target_skill_name+ # Same symlink guard as _register_skills's+ # registration path (#2948).+ if not self._validate_skill_subdir(+ skill_subdir,+ create=True,+ skills_root=skills_dir,+ ):+ continue+ fm_data = registrar.build_skill_frontmatter(+ selected_ai,+ target_skill_name,+ desc,+ f"override:{cmd_name}",+ )+ registrar.apply_argument_hint(+ fm, fm_data, integration+ )+ fm_text = dump_frontmatter(fm_data)+ skill_content = (+ f"---\n{fm_text}\n---\n\n"+ f"# Speckit {skill_title} Skill\n\n{body}\n"+ )+ if integration is not None and hasattr(+ integration, "post_process_skill_content"+ ):+ skill_content = (+ integration.post_process_skill_content(+ skill_content+ )+ )+ _write_shared_text(+ skills_dir,+ skill_subdir / "SKILL.md",+ skill_content,+ )+ wrote_override = True+ if (+ wrote_override+ and (+ target_agent is None+ or dir_agent == target_agent+ )+ ):+ reconciled_skill_commands.add(cmd_name)+ except Exception:+ pass # best-effort override skill restoration++ # Register skills only for the specific commands being+ # reconciled, not all commands in each winning preset's+ # manifest.+ for pack_id, cmds in preset_cmds.items():+ dir_cmds = [+ cmd+ for cmd in cmds+ if any(+ name in dir_managed_names+ for name in self._skill_names_for_command(cmd)+ )+ ]+ if not dir_cmds:+ continue+ pack_dir = self.presets_dir / pack_id+ manifest_path = pack_dir / "preset.yml"+ if not manifest_path.exists():+ continue+ try:+ manifest = PresetManifest(manifest_path)+ except PresetValidationError:+ continue+ cmds_set = set(dir_cmds)+ filtered_manifest = self._FilteredManifest(manifest, cmds_set)+ # Not dead code: _register_skills only *overwrites* skill+ # subdirectories that already exist (plus brand-new ones for+ # the active ai_skills agent). For a restore into a+ # historical directory, _unregister_skills has just deleted+ # the retiring preset's subdirectory, so pre-create the+ # tracked (dir_managed_names) subdirectories here β under+ # the same symlink guard β or the surviving preset's+ # override would be silently skipped (#2948).+ for cmd_name in dir_cmds:+ for skill_name in self._skill_names_for_command(cmd_name):+ if skill_name not in dir_managed_names:+ continue+ skill_subdir = skills_dir / skill_name+ if not self._validate_skill_subdir(+ skill_subdir,+ create=True,+ skills_root=skills_dir,+ ):+ continue+ if is_active:+ # Preserve exact prior behaviour for the currently+ # active directory (including the ability to create+ # brand-new skill subdirectories when ai_skills is on).+ written = self._register_skills(filtered_manifest, pack_dir)+ else:+ written = self._register_skills(+ filtered_manifest, pack_dir,+ target_dir=skills_dir, target_agent=dir_agent or "",+ )+ if target_agent is None:+ written_names = {+ name+ for names in written.values()+ for name in names+ }+ else:+ written_names = set(written.get(target_agent, []))+ for cmd_name in dir_cmds:+ if written_names.intersection(+ self._skill_names_for_command(cmd_name)+ ):+ reconciled_skill_commands.add(cmd_name)+ # The winning preset may not have previously written to+ # this directory's agent (most notably a historical agent+ # reconciliation just restored content into via+ # extra_skills_dirs). If that write isn't merged back into+ # the preset's own registered_skills, its registry entry+ # silently lies about which directories it owns and a+ # later removal of this same preset orphans the directory+ # reconciliation just wrote to on its behalf (#2948).+ self._merge_pack_registered_skills(pack_id, written)++ extra_dirs = extra_skills_dirs or {}+ if active_skills_dir:+ active_provenance = extra_dirs.get(active_skills_dir)+ if extra_skills_dirs is None or active_provenance:+ apply_to_dir(+ active_skills_dir,+ active_ai,+ is_active=True,+ managed_names=(+ set(active_provenance[1])+ if active_provenance+ else None+ ),+ )++ for extra_dir, (extra_agent, extra_names) in extra_dirs.items():+ if extra_dir == active_skills_dir:+ continue # already reconciled above as the active directory+ apply_to_dir(+ extra_dir,+ extra_agent,+ is_active=False,+ managed_names=set(extra_names),+ )++ return reconciled_skill_commands++ def _resolve_agent_skills_dir(self, agent_name: str) -> Path:+ """Resolve the real skill output directory for an integration."""+ from .. import _get_skills_dir as _project_skills_dir+ from ..agents import CommandRegistrar++ registrar = CommandRegistrar()+ agent_config = registrar.AGENT_CONFIGS.get(agent_name)+ if agent_config and agent_config.get("extension") == "/SKILL.md":+ return registrar._resolve_agent_dir(+ agent_name, agent_config, self.project_root+ )+ return _project_skills_dir(self.project_root, agent_name)++ def _skills_validation_root(self, skills_dir: Path) -> Optional[Path]:+ """Return the trusted root containing a project or user skill dir."""+ for root in (self.project_root, Path.home()):+ if skills_dir.is_relative_to(root):+ return root+ return None++ def _get_skills_dir(self) -> Optional[Path]:+ """Return the active skills directory for preset skill overrides.++ Uses :func:`resolve_active_skills_dir` for activation/detection,+ then resolves native skill agents through the registrar's output+ directory so integrations such as Hermes write to their global+ skills path rather than their project-local detection marker.++ Returns ``None`` (instead of raising) when the directory cannot+ be created due to symlink, containment, or permission issues so+ that callers can fall back gracefully.+ """+ from .. import (+ _print_cli_warning,+ load_init_options,+ resolve_active_skills_dir,+ )+ from ..shared_infra import _ensure_safe_shared_directory+ try:+ skills_dir = resolve_active_skills_dir(self.project_root)+ except (ValueError, OSError) as exc:+ _print_cli_warning(+ "resolve", "skills directory", None, exc,+ continuing="Continuing without skill registration.",+ )+ return None+ if skills_dir is None:+ return None++ opts = load_init_options(self.project_root)+ selected_ai = opts.get("ai") if isinstance(opts, dict) else None+ if not isinstance(selected_ai, str) or not selected_ai:+ return skills_dir++ agent_skills_dir = self._resolve_agent_skills_dir(selected_ai)+ if agent_skills_dir == skills_dir:+ return skills_dir++ validation_root = self._skills_validation_root(agent_skills_dir)+ if validation_root is None:+ _print_cli_warning(+ "resolve",+ "skills directory",+ str(agent_skills_dir),+ ValueError("skills directory is outside trusted roots"),+ continuing="Continuing without skill registration.",+ )+ return None+ try:+ _ensure_safe_shared_directory(+ validation_root,+ agent_skills_dir,+ context="preset skills directory",+ )+ except (ValueError, OSError) as exc:+ _print_cli_warning(+ "resolve", "skills directory", str(agent_skills_dir), exc,+ continuing="Continuing without skill registration.",+ )+ return None+ return agent_skills_dir++ @staticmethod+ def _skill_names_for_command(cmd_name: str) -> tuple[str, str]:+ """Return the modern and legacy skill directory names for a command."""+ raw_short_name = cmd_name+ if raw_short_name.startswith("speckit."):+ raw_short_name = raw_short_name[len("speckit."):]++ modern_skill_name = f"speckit-{raw_short_name.replace('.', '-')}"+ legacy_skill_name = f"speckit.{raw_short_name}"+ return modern_skill_name, legacy_skill_name++ @staticmethod+ def _skill_title_from_command(cmd_name: str) -> str:+ """Return a human-friendly title for a skill command name."""+ title_name = cmd_name+ if title_name.startswith("speckit."):+ title_name = title_name[len("speckit."):]+ return title_name.replace(".", " ").replace("-", " ").title()++ @staticmethod+ def _resolve_skill_command_refs(+ body: str,+ registrar: "CommandRegistrar",+ selected_ai: str,+ project_root: "Path | None" = None,+ ) -> str:+ """Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.++ Looks up the agent's invoke separator and rewrites each+ ``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching+ agent-native invocation -- ``/speckit-<cmd>`` or ``$speckit-<cmd>`` for+ a ``-`` separator, ``/speckit.<cmd>`` for ``.``, or+ ``/skill:speckit-<cmd>`` for skill-colon agents (e.g. Kimi) -- the+ same rendering the command layer applies via+ ``CommandRegistrar.register_commands()``.++ For dual-layout agents (e.g. Bob) the separator depends on the+ project's persisted skills state, so -- when *project_root* is provided+ -- the separator is resolved from the integration via+ ``invoke_separator_for_mode`` rather than the single static+ ``AGENT_CONFIGS`` value.+ """+ separator = None+ if project_root is not None and isinstance(selected_ai, str):+ try:+ from .. import load_init_options+ from ..integrations import get_integration++ integration = get_integration(selected_ai)+ if integration is not None:+ separator = integration.invoke_separator_for_mode(+ is_ai_skills_enabled(load_init_options(project_root))+ )+ except Exception:+ separator = None+ if separator is None:+ separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(+ "invoke_separator", "."+ )+ prefix = get_invocation_prefix(selected_ai, separator == "-")+ return IntegrationBase.resolve_command_refs(body, separator, prefix)++ def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:+ """Index extension-backed skill restore data by skill directory name."""+ from ..extensions import ExtensionManifest, ValidationError++ resolver = PresetResolver(self.project_root)+ extensions_dir = self.project_root / ".specify" / "extensions"+ restore_index: Dict[str, Dict[str, Any]] = {}++ for _priority, ext_id, _metadata in resolver._get_all_extensions_by_priority():+ ext_dir = extensions_dir / ext_id+ manifest_path = ext_dir / "extension.yml"+ if not manifest_path.is_file():+ continue++ try:+ manifest = ExtensionManifest(manifest_path)+ except (ValidationError, TypeError, AttributeError):+ continue++ ext_root = ext_dir.resolve()+ for cmd_info in manifest.commands:+ cmd_name = cmd_info.get("name")+ cmd_file_rel = cmd_info.get("file")+ if not isinstance(cmd_name, str) or not isinstance(cmd_file_rel, str):+ continue++ cmd_path = Path(cmd_file_rel)+ if cmd_path.is_absolute():+ continue++ try:+ source_file = (ext_root / cmd_path).resolve()+ source_file.relative_to(ext_root)+ except (OSError, ValueError):+ continue++ if not source_file.is_file():+ continue++ restore_info = {+ "command_name": cmd_name,+ "source_file": source_file,+ "source": f"extension:{manifest.id}",+ "author": manifest.data["extension"].get("author"),+ "extension_id": manifest.id,+ "extension_dir": ext_root,+ }+ modern_skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)+ restore_index.setdefault(modern_skill_name, restore_info)+ if legacy_skill_name != modern_skill_name:+ restore_index.setdefault(legacy_skill_name, restore_info)++ return restore_index++ def _register_skills(+ self,+ manifest: "PresetManifest",+ preset_dir: Path,+ *,+ target_dir: Optional[Path] = None,+ target_agent: Optional[str] = None,+ ) -> Dict[str, List[str]]:+ """Generate SKILL.md files for preset command overrides.++ For every command template in the preset, checks whether a+ corresponding skill already exists in any detected skills+ directory. If so, the skill is overwritten with content derived+ from the preset's command file. This ensures that presets that+ override commands also propagate to the agentskills.io skill+ layer when skills mode was used during project initialisation.++ Args:+ manifest: Preset manifest.+ preset_dir: Installed preset directory.+ target_dir: Explicit skills directory to render into, instead+ of resolving the currently active one. Used by+ ``_reconcile_skills`` to restore a surviving preset's+ override into a historical (currently inactive) agent's+ directory that removal of a higher-priority preset just+ reverted (#2948).+ target_agent: Explicit agent name to render for, paired with+ ``target_dir``. When set, skills are only ever restored+ into already-tracked directories/names β brand-new skill+ subdirectories are never created for a non-active,+ explicitly targeted directory (that creation path is only+ meaningful for the currently active agent).++ Returns:+ ``{agent_name: [skill_name, ...]}`` for the single active+ agent skills were written for (empty if none were written),+ matching the shape ``registered_commands`` already uses so the+ two can be tracked/restored consistently (#2948).+ """+ command_templates = [+ t for t in manifest.templates if t.get("type") == "command"+ ]+ if not command_templates:+ return {}++ # Preset command templates are self-contained and render as skills+ # regardless of whether a like-named extension is installed β the same+ # rule _register_commands() uses. No ``speckit.<ns>.<cmd>`` name-shape+ # filtering; the per-command loop below skips anything without a target+ # skill directory.+ skills_dir = target_dir if target_dir is not None else self._get_skills_dir()+ if not skills_dir:+ return {}++ resolver = PresetResolver(self.project_root)++ from .. import SKILL_DESCRIPTIONS, load_init_options+ from ..agents import CommandRegistrar+ from ..integrations import get_integration+ from ..shared_infra import _write_shared_text++ init_opts = load_init_options(self.project_root)+ if not isinstance(init_opts, dict):+ init_opts = {}+ selected_ai = target_agent if target_agent is not None else init_opts.get("ai")+ if not isinstance(selected_ai, str) or not selected_ai:+ return {}+ # A target_dir/target_agent call reconciles an explicitly-known,+ # already-tracked directory (see _reconcile_skills) rather than the+ # currently active agent, so ai_skills_enabled must not be derived+ # from the *current* project-wide toggle for that other agent β it+ # only controls whether brand-new skill subdirectories may be+ # created below, which is only meaningful for the active agent.+ ai_skills_enabled = target_agent is None and is_ai_skills_enabled(init_opts)+ registrar = CommandRegistrar()+ integration = get_integration(selected_ai)+ agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})+ # Native skill agents (e.g. codex/kimi/agy/trae) materialize brand-new+ # preset skills in _register_commands() because their detected agent+ # directory is already the skills directory. This flag is only for+ # command-backed agents that also mirror commands into skills.+ create_missing_skills = ai_skills_enabled and agent_config.get("extension") != "/SKILL.md"++ written: List[str] = []++ for cmd_tmpl in command_templates:+ cmd_name = cmd_tmpl["name"]+ cmd_file_rel = cmd_tmpl["file"]+ source_file = preset_dir / cmd_file_rel+ if not source_file.exists():+ continue++ # Use composed content if available (written by _register_commands+ # for commands with non-replace strategies), otherwise the original.+ composed_file = preset_dir / ".composed" / f"{cmd_name}.md"+ if composed_file.exists():+ source_file = composed_file++ # Derive the short command name (e.g. "specify" from "speckit.specify")+ raw_short_name = cmd_name+ if raw_short_name.startswith("speckit."):+ raw_short_name = raw_short_name[len("speckit."):]+ short_name = raw_short_name.replace(".", "-")+ skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)+ skill_title = self._skill_title_from_command(cmd_name)++ # Only overwrite skills that already exist under skills_dir,+ # including Kimi native skills when ai_skills is false.+ # If both modern and legacy directories exist, update both.+ target_skill_names: List[str] = []+ if (skills_dir / skill_name).is_dir():+ target_skill_names.append(skill_name)+ if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():+ target_skill_names.append(legacy_skill_name)+ if not target_skill_names and create_missing_skills:+ missing_skill_dir = skills_dir / skill_name+ if not missing_skill_dir.exists():+ target_skill_names.append(skill_name)+ if not target_skill_names:+ continue++ # Parse the command file+ content = source_file.read_text(encoding="utf-8")+ frontmatter, body = registrar.parse_frontmatter(content)++ # A composition-strategy command (wrap/prepend/append) needs a+ # base layer to compose onto. When _register_commands produced no+ # composed file for it and the stack still has no base+ # (resolve_content is None) β e.g. the command it wraps comes from+ # an extension that isn't installed β rendering the raw preset+ # fragment as a skill would emit broken output: a literal+ # {CORE_TEMPLATE} for wrap, or only the preset's own fragment for+ # prepend/append. Skip it here too so command mode and skills mode+ # agree (mirrors _register_commands, which skips the same command).+ # _register_commands already warned for this command in the same+ # pass, so the skip is silent here to avoid a duplicate warning.+ effective_strategy = (+ cmd_tmpl.get("strategy")+ or frontmatter.get("strategy")+ or "replace"+ )+ if (+ effective_strategy != "replace"+ and not composed_file.exists()+ and resolver.resolve_content(cmd_name, "command") is None+ ):+ continue++ if frontmatter.get("strategy") == "wrap":+ body, core_frontmatter = _substitute_core_template(body, cmd_name, self.project_root, registrar)+ frontmatter = dict(frontmatter)+ for key in ("scripts", "agent_scripts", "argument-hint"):+ if key not in frontmatter and key in core_frontmatter:+ frontmatter[key] = core_frontmatter[key]++ original_desc = frontmatter.get("description", "")+ enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(+ short_name,+ f"Spec-kit workflow command: {short_name}",+ )+ frontmatter = dict(frontmatter)+ frontmatter["description"] = enhanced_desc+ body = registrar.resolve_skill_placeholders(+ selected_ai, frontmatter, body, self.project_root+ )+ body = self._resolve_skill_command_refs(body, registrar, selected_ai, self.project_root)++ for target_skill_name in target_skill_names:+ skill_subdir = skills_dir / target_skill_name+ if skill_subdir.exists() and not skill_subdir.is_dir():+ continue+ # Validate (and create, if missing) the skill's own+ # subdirectory under the same symlink guard as its parent β+ # is_dir() above follows symlinks, so a symlinked subdir+ # with a real parent would otherwise slip through and have+ # SKILL.md written through it to an arbitrary location (#2948).+ if not self._validate_skill_subdir(+ skill_subdir, create=True, skills_root=skills_dir+ ):+ continue+ frontmatter_data = registrar.build_skill_frontmatter(+ selected_ai,+ target_skill_name,+ enhanced_desc,+ f"preset:{manifest.id}",+ )+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)+ frontmatter_text = dump_frontmatter(frontmatter_data)+ skill_content = (+ f"---\n"+ f"{frontmatter_text}\n"+ f"---\n\n"+ f"# Speckit {skill_title} Skill\n\n"+ f"{body}\n"+ )+ if integration is not None and hasattr(integration, "post_process_skill_content"):+ skill_content = integration.post_process_skill_content(+ skill_content+ )++ skill_file = skill_subdir / "SKILL.md"+ _write_shared_text(+ skills_dir, skill_file, skill_content+ )+ written.append(target_skill_name)+ self._merge_pack_registered_skills(+ manifest.id, {selected_ai: [target_skill_name]}+ )++ return {selected_ai: written} if written else {}++ def _infer_legacy_skill_provenance(+ self, skill_names: List[str], pack_id: str, fallback_agent: str+ ) -> Dict[str, List[str]]:+ """Infer per-agent ownership of a legacy flat-list ``registered_skills`` value.++ Pre-#2948 registries recorded ``registered_skills`` as a flat list+ with no record of which agent directory each name was actually+ written under. Blindly attributing every name to ``fallback_agent``+ (the agent currently being processed) loses the real writer whenever+ the *first* operation after upgrading is a direct switch to a+ *different* agent β e.g. a legacy Copilot override (written while+ Copilot was active with ``ai_skills`` enabled) followed directly by+ ``integration use claude``, with no intervening rescaffold for+ Copilot β permanently orphaning Copilot's override on later+ removal.++ Every project-local configured integration's skills directory is probed (via+ the same safe, symlink-validated helpers used for+ restore/removal), not only agents whose registrar config is+ statically ``/SKILL.md``-only: a command-backed agent (e.g.+ Copilot, whose command extension is ``.agent.md``) renders its+ preset overrides as ``SKILL.md`` files exactly like a native+ skill-only agent whenever it was the active agent with+ ``ai_skills`` enabled, so excluding it would miss real,+ preset-owned provenance and misattribute it to whichever agent+ happens to be processed first. Each directory is probed for a+ ``SKILL.md`` whose frontmatter records this exact preset as the+ owner (``metadata.source == "preset:<pack_id>"``, the same marker+ :meth:`_register_skills` writes) β this marker check is what keeps+ the broadened probe from falsely attributing ownership to an+ agent's directory that never actually held this preset's override+ (e.g. a command-mode agent that never rendered skills, or an+ unrelated skill of the same name). A name can legitimately be+ found under more than one agent's directory β the preset may have+ been active while the user switched between several agents before+ provenance tracking existed β so every matching agent is recorded,+ not just the first. Names that can't be matched to any directory+ (e.g. the file was deleted out of band) fall back to+ ``fallback_agent``, preserving the previous best-effort behaviour+ for the unrecoverable case.+ """+ from ..agents import CommandRegistrar++ registrar = CommandRegistrar()+ candidate_agents = sorted(registrar.AGENT_CONFIGS)++ # Multiple agent names can resolve to the same physical directory+ # (e.g. agy/amp/codex/zed all use .agents/skills); group by+ # directory so each is probed once and attributed to a single+ # deterministic canonical agent name, matching the tie-break+ # already used by _unregister_skills's directory grouping. Deliberately+ # keep the unresolved path (matching what _safe_skills_dir_for_agent+ # already validated) rather than calling .resolve() here: on macOS+ # /var is itself a symlink to /private/var, so resolving would make+ # this path diverge from self.project_root's own resolution state+ # and make every subsequent containment check in+ # _validate_skill_subdir() spuriously fail.+ dir_to_agents: Dict[Path, List[str]] = {}+ for agent_name in candidate_agents:+ skills_dir = self._safe_skills_dir_for_agent(agent_name)+ if skills_dir is None:+ continue+ # Only project-local skills directories are eligible: the+ # legacy provenance markers don't record which project owns a+ # skill under a home directory, so deletion stays restricted+ # to the project root. Revisit if provenance ever records the+ # owning project.+ if not Path(os.path.abspath(skills_dir)).is_relative_to(+ Path(os.path.abspath(self.project_root))+ ):+ continue+ dir_to_agents.setdefault(skills_dir, []).append(agent_name)++ marker = f"preset:{pack_id}"+ # Filter unsafe names once, up front, rather than only inside the+ # matching loop: any name skipped there would otherwise still+ # land in "unmatched" below and get blindly attributed to+ # fallback_agent anyway, defeating the guard entirely (#2948).+ safe_skill_names = [+ name for name in skill_names if self._is_safe_registry_skill_name(name)+ ]+ inferred: Dict[str, List[str]] = {}+ matched_names: set = set()+ for resolved_dir, agents in dir_to_agents.items():+ canonical_agent = fallback_agent if fallback_agent in agents else sorted(agents)[0]+ for name in safe_skill_names:+ skill_subdir = resolved_dir / name+ if not self._validate_skill_subdir(+ skill_subdir, create=False, skills_root=resolved_dir+ ):+ continue+ skill_file = skill_subdir / "SKILL.md"+ if not skill_file.is_file():+ continue+ try:+ content = skill_file.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ continue+ frontmatter, _ = registrar.parse_frontmatter(content)+ skill_metadata = frontmatter.get("metadata")+ source = (+ skill_metadata.get("source")+ if isinstance(skill_metadata, dict)+ else None+ )+ if source == marker:+ inferred.setdefault(canonical_agent, []).append(name)+ matched_names.add(name)++ unmatched = [name for name in safe_skill_names if name not in matched_names]+ if unmatched and fallback_agent:+ fallback_names = inferred.setdefault(fallback_agent, [])+ for name in unmatched:+ if name not in fallback_names:+ fallback_names.append(name)++ return inferred++ @staticmethod+ def _normalize_registered_skills(+ value: Any, fallback_agent: Optional[str] = None+ ) -> Dict[str, List[str]]:+ """Normalize a ``registered_skills`` registry value to per-agent form.++ The registry stores ``registered_skills`` as ``Dict[str, List[str]]``+ (agent name -> skill names actually written for that agent),+ mirroring ``registered_commands``. Older registries predate that+ provenance and stored a flat ``List[str]`` with no record of which+ agent directory the names were written under; since that can't be+ recovered, ``fallback_agent`` (when given) attributes the legacy+ list to the agent currently being processed so the format+ self-migrates on the next write. Without a fallback agent, legacy+ lists are dropped rather than guessed at.++ Callers that can identify the owning preset (i.e. have a+ ``pack_id``) should prefer :meth:`_infer_legacy_skill_provenance`+ for a legacy flat-list value instead, which probes on-disk+ provenance rather than assuming ``fallback_agent`` wrote every name.+ """+ if isinstance(value, dict):+ return {+ agent: list(names)+ for agent, names in value.items()+ if isinstance(agent, str) and isinstance(names, list)+ }+ if isinstance(value, list) and value and fallback_agent:+ return {fallback_agent: [n for n in value if isinstance(n, str)]}+ return {}++ def _safe_skills_dir_for_agent(self, agent_name: str) -> Optional[Path]:+ """Resolve ``agent_name``'s skills directory, validated for safety.++ Unlike :meth:`_get_skills_dir` (which resolves only the *currently+ active* integration via init-options), this resolves an arbitrary+ agent's directory from persisted provenance so a preset's skill+ registrations can be restored/cleaned up under an agent that isn't+ currently active. The candidate directory is validated through the+ project's shared symlink/containment guard before any file in it is+ touched; directories that don't exist or fail validation are+ skipped rather than raising.+ """+ from ..agents import CommandRegistrar+ from ..shared_infra import _ensure_safe_shared_directory++ if agent_name not in CommandRegistrar.AGENT_CONFIGS:+ return None+ skills_dir = self._resolve_agent_skills_dir(agent_name)+ validation_root = self._skills_validation_root(skills_dir)+ if validation_root is None:+ return None+ try:+ _ensure_safe_shared_directory(+ validation_root, skills_dir,+ create=False, context="preset skills directory",+ )+ except (ValueError, OSError):+ return None+ return skills_dir++ @staticmethod+ def _is_safe_registry_skill_name(name: Any) -> bool:+ """Validate a registry-provided skill name is a single safe path component.++ ``registered_skills`` entries are persisted registry data, not+ derived from the current preset manifest, so a corrupted or+ maliciously edited registry could contain an absolute path, a+ multi-segment path (containing ``/`` or ``\\``), or a traversal+ component (``"."``/``".."``) instead of a plain skill directory+ name. Any of these β if joined directly onto a skills directory β+ can escape the intended skill subtree while still resolving to a+ location inside the project root, which is enough to pass the+ parent-directory containment/symlink check alone (#2948). This+ centralizes the single boundary check every preset cleanup and+ provenance loop that consumes registry-provided skill names must+ apply before ever constructing a path from one.+ """+ if not isinstance(name, str) or not name:+ return False+ if name in (".", ".."):+ return False+ candidate = Path(name)+ if candidate.is_absolute():+ return False+ if len(candidate.parts) != 1:+ return False+ if candidate.name != name:+ return False+ return True++ def _validate_skill_subdir(+ self,+ skill_subdir: Path,+ *,+ create: bool,+ skills_root: Optional[Path] = None,+ ) -> bool:+ """Validate a single skill's subdirectory is symlink-free.++ Unlike :meth:`_safe_skills_dir_for_agent` (which only validates the+ *parent* skills directory), this validates the skill's own+ subdirectory β e.g. ``.claude/skills/speckit-specify`` β so a+ symlink planted at that level (with a safe parent) can't be used to+ write or delete through to a location outside the project. Shared by+ both the registration path (``create=True``, so a missing directory+ is created component-by-component under the same guard) and the+ restore/removal path (``create=False``, so a missing directory is+ left for the caller's own existence check to skip). Returns+ ``False`` rather than raising when the path escapes the project+ root or crosses a symlink. ``skills_root`` supplies the trusted+ agent output boundary for native global skill integrations such as+ Hermes; project-local callers default to ``self.project_root``.+ """+ from ..shared_infra import (+ _ensure_safe_shared_directory,+ _validate_safe_shared_directory,+ )++ validation_root = skills_root or self.project_root+ if validation_root.is_symlink():+ return False+ try:+ if create:+ _ensure_safe_shared_directory(+ validation_root, skill_subdir,+ create=True, context="preset skill directory",+ )+ else:+ _validate_safe_shared_directory(+ validation_root, skill_subdir+ )+ except (ValueError, OSError):+ return False+ return True++ def _unregister_skills(+ self,+ registered_skills: Union[Dict[str, List[str]], List[str]],+ preset_dir: Union[Path, str],+ *,+ additional_owned_sources: Optional[Dict[str, str]] = None,+ restore_from_bundled_core: bool = False,+ ) -> Dict[Path, tuple[Optional[str], List[str]]]:+ """Restore original SKILL.md files after a preset is removed.++ For each skill that was overridden by the preset, attempts to+ regenerate the skill from the core command template. If no core+ template exists, the skill directory is removed.++ Args:+ restore_from_bundled_core: When True, a missing project-local+ core template (the common case β ``specify init`` never+ populates ``.specify/templates/commands``) falls back to+ the bundled core_pack/repo-root templates so the skill is+ restored instead of deleted (#3928). Callers that are+ retiring a skill because its command now renders elsewhere+ (a command file superseding it) must leave this False so+ the skill is removed rather than resurrected with core+ content that would duplicate the winning command.++ ``registered_skills`` records exactly which agent directories this+ preset actually wrote to (see :meth:`_register_skills`), so removal+ restores precisely those directories rather than guessing at every+ skill-mode agent that happens to exist on disk. Each directory is+ re-resolved and safety-validated at removal time (see+ :meth:`_safe_skills_dir_for_agent`) since it may belong to an agent+ that isn't currently active.++ Args:+ registered_skills: Per-agent skill names written by the preset+ (``{agent_name: [skill_name, ...]}``), or a legacy flat+ ``List[str]`` from a registry written before this+ provenance tracking existed.+ preset_dir: The preset's installed directory (may already be deleted).+ additional_owned_sources: Generated non-preset source markers+ that this cleanup may also replace for specific skill names.++ Returns:+ ``{skills_dir: (renderer_agent, managed_skill_names)}`` for+ every directory and skill name actually restored or removed.+ """+ if not registered_skills:+ return {}++ pack_id = preset_dir if isinstance(preset_dir, str) else preset_dir.name++ if isinstance(registered_skills, dict):+ from .. import load_init_options++ init_opts = load_init_options(self.project_root)+ active_agent = init_opts.get("ai") if isinstance(init_opts, dict) else None+ if not isinstance(active_agent, str) or not active_agent:+ active_agent = None++ # Multiple integration keys can share the same physical+ # directory (e.g. agy/codex/zed all resolve to+ # ``.agents/skills``). Restoring that directory once per+ # recorded agent would have each pass's agent-specific+ # rendering (frontmatter, post-processing) overwrite the+ # previous one, with whichever agent is iterated *last* silently+ # winning regardless of which agent is actually active. Group+ # provenance by resolved directory so each physical directory is+ # restored exactly once, using the active agent's renderer when+ # it shares that directory (otherwise any recorded owner,+ # chosen deterministically).+ groups: Dict[Path, Dict[str, Any]] = {}+ for agent_name, skill_names in registered_skills.items():+ if not skill_names:+ continue+ skills_dir = self._safe_skills_dir_for_agent(agent_name)+ if skills_dir is None:+ continue+ group = groups.setdefault(skills_dir, {"agents": [], "names": []})+ group["agents"].append(agent_name)+ for name in skill_names:+ if (+ self._is_safe_registry_skill_name(name)+ and name not in group["names"]+ ):+ group["names"].append(name)++ restored: Dict[Path, tuple[Optional[str], List[str]]] = {}+ for skills_dir, group in groups.items():+ agents = group["agents"]+ renderer_agent = (+ active_agent if active_agent in agents else sorted(agents)[0]+ )+ mutated_names = self._unregister_skills_in_dir(+ group["names"],+ skills_dir,+ renderer_agent,+ pack_id=pack_id,+ additional_owned_sources=additional_owned_sources,+ restore_from_bundled_core=restore_from_bundled_core,+ )+ if mutated_names:+ restored[skills_dir] = (+ renderer_agent,+ mutated_names,+ )+ return restored++ # Legacy flat-list format: no record of which agent directory these+ # names were written under, so best-effort restore is limited to the+ # currently active agent's directory (the pre-provenance behaviour).+ skills_dir = self._get_skills_dir()+ if not skills_dir:+ return {}+ from .. import load_init_options++ init_opts = load_init_options(self.project_root)+ if not isinstance(init_opts, dict):+ init_opts = {}+ selected_ai = init_opts.get("ai")+ selected_ai = selected_ai if isinstance(selected_ai, str) else None+ safe_names = [+ name+ for name in registered_skills+ if self._is_safe_registry_skill_name(name)+ ]+ mutated_names = self._unregister_skills_in_dir(+ safe_names,+ skills_dir,+ selected_ai,+ pack_id=pack_id,+ additional_owned_sources=additional_owned_sources,+ restore_from_bundled_core=restore_from_bundled_core,+ )+ return (+ {skills_dir: (selected_ai, mutated_names)}+ if mutated_names+ else {}+ )++ def _delete_agent_preset_skills(+ self, agent_name: str, skill_names: List[str], pack_id: str+ ) -> None:+ """Delete still-preset-owned skills when an agent is deactivated."""+ skills_dir = self._safe_skills_dir_for_agent(agent_name)+ if skills_dir is None:+ return++ from ..agents import CommandRegistrar++ registrar = CommandRegistrar()+ marker = f"preset:{pack_id}"+ override_sources: Dict[str, str] = {}+ manifest = PresetResolver(self.project_root)._get_manifest(+ self.presets_dir / pack_id+ )+ if manifest is not None:+ for template in manifest.templates:+ command_name = template.get("name")+ if (+ template.get("type") == "command"+ and isinstance(command_name, str)+ ):+ for skill_name in self._skill_names_for_command(+ command_name+ ):+ override_sources[skill_name] = (+ f"override:{command_name}"+ )+ for skill_name in skill_names:+ if not self._is_safe_registry_skill_name(skill_name):+ continue+ skill_subdir = skills_dir / skill_name+ if not self._validate_skill_subdir(+ skill_subdir, create=False, skills_root=skills_dir+ ):+ continue+ skill_file = skill_subdir / "SKILL.md"+ if not skill_file.is_file():+ continue+ try:+ content = skill_file.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ continue+ frontmatter, _ = registrar.parse_frontmatter(content)+ metadata = frontmatter.get("metadata")+ source = (+ metadata.get("source")+ if isinstance(metadata, dict)+ else None+ )+ owned_sources = {marker}+ override_source = override_sources.get(skill_name)+ if override_source:+ owned_sources.add(override_source)+ if source in owned_sources:+ shutil.rmtree(skill_subdir)++ @staticmethod+ def _warn_unrestored_skill(+ skill_name: str, source_file: Path, exc: BaseException+ ) -> None:+ """Warn that a skill kept preset content because its restore source is unreadable.++ Skipping the restore is the safe recovery β the alternative branch+ deletes the skill outright β but it is still a partial removal: the+ preset directory and registry entry go away while this ``SKILL.md``+ keeps the removed preset's content, and reconciliation never revisits+ it because the name is left out of ``mutated_names``. Name the skill+ and the source so the condition is actionable instead of silent.+ """+ import warnings++ warnings.warn(+ f"Skill '{skill_name}' still contains the removed preset's content: "+ f"its restore source '{source_file}' could not be read "+ f"({exc.__class__.__name__}: {exc}). The skill was left in place "+ f"rather than deleted. Fix or remove that file and re-run "+ f"'specify preset add'/'specify preset remove' to refresh it.",+ stacklevel=2,+ )++ def _unregister_skills_in_dir(+ self,+ skill_names: List[str],+ skills_dir: Path,+ selected_ai: Optional[str],+ *,+ pack_id: Optional[str] = None,+ additional_owned_sources: Optional[Dict[str, str]] = None,+ restore_from_bundled_core: bool = False,+ ) -> List[str]:+ """Restore original SKILL.md files within a single skills directory.++ Args:+ skill_names: List of skill names written by the preset.+ skills_dir: The skills directory to restore within.+ selected_ai: The agent name that owns ``skills_dir``, used for+ placeholder resolution and argument-hint formatting.+ additional_owned_sources: Generated non-preset source markers+ accepted as owned for specific skill names.+ restore_from_bundled_core: See ``_unregister_skills``.++ Returns:+ Skill names whose files were restored or removed.+ """+ from .. import SKILL_DESCRIPTIONS+ from ..agents import CommandRegistrar+ from ..integrations import get_integration+ from ..shared_infra import _write_shared_text++ # Locate core command templates from the project's installed templates+ core_templates_dir = self.project_root / ".specify" / "templates" / "commands"+ registrar = CommandRegistrar()+ integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None+ extension_restore_index = self._build_extension_skill_restore_index()+ mutated_names: List[str] = []++ for skill_name in skill_names:+ # Guard against a corrupted/malicious registry entry: a+ # registered_skills name is persisted data, not derived from+ # the current manifest, so it must be validated as a single,+ # relative, non-"."/".." path component before ever being+ # joined onto skills_dir. Without this, an absolute name+ # discards skills_dir entirely (Path's "/" operator drops the+ # left side for an absolute right side) or a multi-component+ # name containing ".." can resolve to a different, unrelated+ # directory that still happens to be inside the project root+ # β passing the containment-only symlink guard below and+ # letting removal overwrite/delete it (#2948).+ if not self._is_safe_registry_skill_name(skill_name):+ continue++ # Derive command name from skill name (speckit-specify -> specify)+ short_name = skill_name+ if short_name.startswith("speckit-"):+ short_name = short_name[len("speckit-"):]+ elif short_name.startswith("speckit."):+ short_name = short_name[len("speckit."):]++ skill_subdir = skills_dir / skill_name+ skill_file = skill_subdir / "SKILL.md"+ if not skill_subdir.is_dir():+ continue+ # is_dir() follows symlinks, so a symlinked skill subdirectory+ # (with a safe, non-symlinked parent) would otherwise slip past+ # _safe_skills_dir_for_agent's parent-only check and have+ # write_text/rmtree operate through it (#2948).+ if not self._validate_skill_subdir(+ skill_subdir, create=False, skills_root=skills_dir+ ):+ continue+ if not skill_file.is_file():+ # Only manage directories that contain the expected skill entrypoint.+ continue+ if pack_id is not None:+ try:+ current_content = skill_file.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ continue+ current_frontmatter, _ = registrar.parse_frontmatter(current_content)+ current_metadata = current_frontmatter.get("metadata")+ current_source = (+ current_metadata.get("source")+ if isinstance(current_metadata, dict)+ else None+ )+ owned_sources = {f"preset:{pack_id}"}+ if additional_owned_sources:+ additional_source = additional_owned_sources.get(+ skill_name+ )+ if additional_source:+ owned_sources.add(additional_source)+ if current_source not in owned_sources:+ continue++ extension_restore = extension_restore_index.get(skill_name)++ # Try to find the core command template. Project-local overrides+ # in core_templates_dir take precedence, but that directory is+ # rarely populated β the real core commands ship in the bundled+ # core_pack (wheel install) or the repo-root templates/ tree+ # (source checkout). Callers that want a genuine restore (a+ # preset was removed outright, not superseded by another+ # renderer) opt into that fallback via restore_from_bundled_core+ # so the skill is restored instead of deleted (#3928). An+ # installed extension providing a core-named command resolves+ # ahead of bundled core elsewhere, so skip the bundled fallback+ # when an extension restore exists β otherwise it would win+ # over the higher-priority extension layer below.+ core_file = core_templates_dir / f"{short_name}.md"+ if (+ not core_file.exists()+ and restore_from_bundled_core+ and extension_restore is None+ ):+ from .. import _locate_core_pack, _repo_root++ _core_pack = _locate_core_pack()+ if _core_pack is not None:+ core_file = _core_pack / "commands" / f"{short_name}.md"+ else:+ core_file = _repo_root() / "templates" / "commands" / f"{short_name}.md"+ if not core_file.exists():+ core_file = None++ if core_file:+ # Restore from core template. An unreadable/undecodable+ # source cannot produce restored content, so leave the+ # existing skill untouched rather than leaking a raw+ # OSError/UnicodeDecodeError out of `preset remove` β and+ # rather than falling through to the rmtree below, which+ # would delete a skill precisely when its replacement+ # cannot be generated. Matches the `continue` guards above+ # (unsafe name, missing subdir, foreign owner), which also+ # skip without recording the name as mutated.+ try:+ content = core_file.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError) as exc:+ self._warn_unrestored_skill(skill_name, core_file, exc)+ continue+ frontmatter, body = registrar.parse_frontmatter(content)+ if isinstance(selected_ai, str):+ body = registrar.resolve_skill_placeholders(+ selected_ai, frontmatter, body, self.project_root+ )+ body = self._resolve_skill_command_refs(+ body, registrar, selected_ai, self.project_root+ )++ original_desc = frontmatter.get("description", "")+ enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(+ short_name,+ f"Spec-kit workflow command: {short_name}",+ )++ frontmatter_data = registrar.build_skill_frontmatter(+ selected_ai if isinstance(selected_ai, str) else "",+ skill_name,+ enhanced_desc,+ f"templates/commands/{short_name}.md",+ )+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)+ frontmatter_text = dump_frontmatter(frontmatter_data)+ skill_title = self._skill_title_from_command(short_name)+ skill_content = (+ f"---\n"+ f"{frontmatter_text}\n"+ f"---\n\n"+ f"# Speckit {skill_title} Skill\n\n"+ f"{body}\n"+ )+ if integration is not None and hasattr(integration, "post_process_skill_content"):+ skill_content = integration.post_process_skill_content(+ skill_content+ )+ _write_shared_text(skills_dir, skill_file, skill_content)+ mutated_names.append(skill_name)+ continue++ if extension_restore:+ # Same boundary as the core-template branch above: an+ # unreadable extension source leaves the skill in place+ # instead of crashing or being deleted.+ try:+ content = extension_restore["source_file"].read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError) as exc:+ self._warn_unrestored_skill(+ skill_name, extension_restore["source_file"], exc+ )+ continue+ frontmatter, body = registrar.parse_frontmatter(content)+ # Mirror the register-time rewrite (#2101): resolve+ # extension-relative subdir references (agents/,+ # knowledge-base/, etc.) to their installed location before+ # the generic placeholder resolution below, otherwise+ # restoring after a preset override removal would leave+ # bare, unresolvable paths in the skill body.+ body = registrar.rewrite_extension_paths(+ body,+ extension_restore["extension_id"],+ extension_restore["extension_dir"],+ )+ if isinstance(selected_ai, str):+ body = registrar.resolve_skill_placeholders(+ selected_ai, frontmatter, body, self.project_root+ )+ body = self._resolve_skill_command_refs(+ body, registrar, selected_ai, self.project_root+ )++ command_name = extension_restore["command_name"]+ title_name = self._skill_title_from_command(command_name)++ frontmatter_data = registrar.build_skill_frontmatter(+ selected_ai if isinstance(selected_ai, str) else "",+ skill_name,+ frontmatter.get("description", f"Extension command: {command_name}"),+ extension_restore["source"],+ author=extension_restore.get("author", "github-spec-kit"),+ )+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)+ frontmatter_text = dump_frontmatter(frontmatter_data)+ skill_content = (+ f"---\n"+ f"{frontmatter_text}\n"+ f"---\n\n"+ f"# {title_name} Skill\n\n"+ f"{body}\n"+ )+ if integration is not None and hasattr(integration, "post_process_skill_content"):+ skill_content = integration.post_process_skill_content(+ skill_content+ )+ _write_shared_text(skills_dir, skill_file, skill_content)+ mutated_names.append(skill_name)+ else:+ # No core or extension template β remove the skill entirely+ shutil.rmtree(skill_subdir)+ mutated_names.append(skill_name)++ return mutated_namesdiff --git a/src/specify_cli/presets/_manifest.py b/src/specify_cli/presets/_manifest.pynew file mode 100644index 000000000..b5a7ff03c--- /dev/null+++ b/src/specify_cli/presets/_manifest.py@@ -0,0 +1,438 @@+"""Preset manifest validation and domain errors (private implementation)."""++import hashlib+import os+import re+from pathlib import Path+from typing import Any, Dict, List++import yaml+from packaging import version as pkg_version+from packaging.specifiers import InvalidSpecifier, SpecifierSet+++class PresetError(Exception):+ """Base exception for preset-related errors."""+ pass+++class PresetValidationError(PresetError):+ """Raised when preset manifest validation fails."""+ pass+++class PresetCompatibilityError(PresetError):+ """Raised when preset is incompatible with current environment."""+ pass+++VALID_PRESET_TEMPLATE_TYPES = {"template", "command", "script"}+VALID_PRESET_STRATEGIES = {"replace", "prepend", "append", "wrap"}+# Scripts only support replace and wrap (prepend/append don't make semantic sense for executable code)+VALID_SCRIPT_STRATEGIES = {"replace", "wrap"}+++class PresetManifest:+ """Represents and validates a preset manifest (preset.yml)."""++ SCHEMA_VERSION = "1.0"+ REQUIRED_FIELDS = ["schema_version", "preset", "requires", "provides"]++ def __init__(self, manifest_path: Path):+ """Load and validate preset manifest.++ Args:+ manifest_path: Path to preset.yml file++ Raises:+ PresetValidationError: If manifest is invalid+ """+ self.path = manifest_path+ self.data = self._load_yaml(manifest_path)+ self._validate()++ def _load_yaml(self, path: Path) -> dict:+ """Load YAML file safely."""+ try:+ with open(path, 'r', encoding='utf-8') as f:+ data = yaml.safe_load(f)+ except yaml.YAMLError as e:+ raise PresetValidationError(f"Invalid YAML in {path}: {e}")+ except FileNotFoundError:+ raise PresetValidationError(f"Manifest not found: {path}")+ except UnicodeDecodeError as e:+ raise PresetValidationError(+ f"Manifest is not valid UTF-8: {path} ({e.reason} at byte {e.start})"+ )+ except OSError as e:+ raise PresetValidationError(f"Could not read manifest {path}: {e}")+ if data is None:+ return {}+ if not isinstance(data, dict):+ raise PresetValidationError(+ f"Manifest must be a YAML mapping, got {type(data).__name__}: {path}"+ )+ return data++ def _validate(self):+ """Validate manifest structure and required fields."""+ # Check required top-level fields+ for field in self.REQUIRED_FIELDS:+ if field not in self.data:+ raise PresetValidationError(f"Missing required field: {field}")++ # Validate schema version+ if self.data["schema_version"] != self.SCHEMA_VERSION:+ raise PresetValidationError(+ f"Unsupported schema version: {self.data['schema_version']} "+ f"(expected {self.SCHEMA_VERSION})"+ )++ for section in ("preset", "requires", "provides"):+ if not isinstance(self.data[section], dict):+ raise PresetValidationError(+ f"Invalid {section}: expected a mapping"+ )++ # Validate preset metadata+ pack = self.data["preset"]+ # Check presence AND type: the format/version checks below feed these+ # values straight to ``re.match`` and ``packaging.Version``, both of+ # which raise a bare TypeError on a non-string. YAML makes that an easy+ # authoring slip -- unquoted ``version: 1.0`` parses as a float and+ # ``id: 2`` as an int -- and TypeError is not a PresetValidationError,+ # so it escapes every caller that already handles a malformed manifest+ # (see list_installed()'s "Corrupted preset" fallback, which catches+ # PresetValidationError only, making one bad preset exit ``specify+ # preset list`` with a raw traceback and hide the healthy ones).+ # Mirrors the sibling IntegrationDescriptor, which already type-checks+ # the same four fields.+ for field in ["id", "name", "version", "description"]:+ if field not in pack:+ raise PresetValidationError(f"Missing preset.{field}")+ if not isinstance(pack[field], str):+ raise PresetValidationError(+ f"Invalid preset.{field}: expected a string, "+ f"got {type(pack[field]).__name__}"+ )++ # Validate pack ID format+ if not re.match(r'^[a-z0-9-]+$', pack["id"]):+ raise PresetValidationError(+ f"Invalid preset ID '{pack['id']}': "+ "must be lowercase alphanumeric with hyphens only"+ )++ # Validate semantic version+ try:+ pkg_version.Version(pack["version"])+ except pkg_version.InvalidVersion:+ raise PresetValidationError(f"Invalid version: {pack['version']}")++ # Validate requires section+ requires = self.data["requires"]+ if "speckit_version" not in requires:+ raise PresetValidationError("Missing requires.speckit_version")+ # Presence alone is not enough: check_compatibility() feeds this value to+ # ``SpecifierSet(required)``, guarded only by ``except InvalidSpecifier``,+ # which a non-string escapes two different ways. A float/int/bool/None+ # raises TypeError from the constructor, while a list or dict is an+ # *iterable*, so SpecifierSet accepts it and the failure surfaces much+ # later as ``AttributeError: 'str' object has no attribute 'filter'`` from+ # inside .contains(). Neither is a PresetCompatibilityError, so both+ # bypass the CLI's "Compatibility Error" handler and exit 1 with a raw+ # traceback naming no field. An unquoted ``speckit_version: 1.0`` is an+ # easy YAML slip. Mirrors the sibling IntegrationDescriptor, which already+ # requires a non-empty string here.+ if (+ not isinstance(requires["speckit_version"], str)+ or not requires["speckit_version"].strip()+ ):+ raise PresetValidationError(+ "Invalid requires.speckit_version: expected a non-empty string, "+ f"got {type(requires['speckit_version']).__name__}"+ )++ # Validate the optional extension dependency list. A preset that+ # overrides commands calling into an extension is inert without it, and+ # until now the only place that could be said was the README -- see+ # issue #4231. Absent means "no dependencies", so every existing preset+ # stays valid.+ if "extensions" in requires:+ self._validate_requires_extensions(requires["extensions"])++ # Validate provides section+ provides = self.data["provides"]+ if "templates" not in provides:+ raise PresetValidationError(+ "Preset must provide at least one template"+ )++ # Validate templates. Guard the container and each entry's shape so a+ # malformed third-party preset.yml (e.g. ``templates: 5`` or+ # ``templates: [null]``) raises a clean PresetValidationError the+ # install handler already catches, instead of a raw TypeError+ # ('int'/'NoneType' object is not iterable) that escapes to an+ # unhandled traceback. Mirrors the sibling ExtensionManifest guards.+ #+ # Order matters: the container's TYPE is checked before its emptiness,+ # so a FALSY non-list (``templates: 0``/``false``/``null``/``''``/``{}``)+ # reports the accurate type error rather than the misleading "must+ # provide at least one template". An empty list still reports the+ # latter, since that genuinely is a list with no templates.+ templates = provides["templates"]+ if not isinstance(templates, list):+ raise PresetValidationError(+ "Invalid provides.templates: expected a list"+ )+ if not templates:+ raise PresetValidationError(+ "Preset must provide at least one template"+ )+ seen_name_types: set[tuple[str, str]] = set()+ for tmpl in templates:+ if not isinstance(tmpl, dict):+ raise PresetValidationError(+ "Each template entry in 'provides.templates' must be a mapping"+ )+ if "type" not in tmpl or "name" not in tmpl or "file" not in tmpl:+ raise PresetValidationError(+ "Template missing 'type', 'name', or 'file'"+ )++ # 'name' feeds re.match and 'file' feeds os.path.normpath below;+ # both raise a bare TypeError on a non-string, which is not a+ # PresetValidationError and so escapes the callers that handle a+ # malformed manifest. The sibling extension manifest already+ # rejects a non-string command 'file' via+ # relative_extension_path_violation().+ for field in ("type", "name", "file"):+ if not isinstance(tmpl[field], str):+ raise PresetValidationError(+ f"Invalid template {field}: expected a string, "+ f"got {type(tmpl[field]).__name__}"+ )++ if tmpl["type"] not in VALID_PRESET_TEMPLATE_TYPES:+ raise PresetValidationError(+ f"Invalid template type '{tmpl['type']}': "+ f"must be one of {sorted(VALID_PRESET_TEMPLATE_TYPES)}"+ )++ # PresetResolver._manifest_declared_template returns the first+ # 'provides.templates' entry matching a given (name, type) pair, so+ # a later duplicate would be silently unreachable while still being+ # counted by PresetManifest.templates. Reject at validation time+ # instead, mirroring the sibling fix for ExtensionManifest's+ # provides.templates/scripts (#4016).+ name_type = (tmpl["name"], tmpl["type"])+ if name_type in seen_name_types:+ raise PresetValidationError(+ f"Duplicate template name '{tmpl['name']}' of type "+ f"'{tmpl['type']}' in 'provides.templates'"+ )+ seen_name_types.add(name_type)++ # Validate file path safety: must be relative, no parent traversal+ file_path = tmpl["file"]+ normalized = os.path.normpath(file_path)+ if os.path.isabs(normalized) or normalized.startswith(".."):+ raise PresetValidationError(+ f"Invalid template file path '{file_path}': "+ "must be a relative path within the preset directory"+ )++ # Validate strategy field (optional, defaults to "replace")+ strategy = tmpl.get("strategy", "replace")+ if not isinstance(strategy, str):+ raise PresetValidationError(+ f"Invalid strategy value: must be a string, "+ f"got {type(strategy).__name__}"+ )+ strategy = strategy.lower()+ # Persist normalized value so downstream code sees lowercase+ if "strategy" in tmpl:+ tmpl["strategy"] = strategy+ if strategy not in VALID_PRESET_STRATEGIES:+ raise PresetValidationError(+ f"Invalid strategy '{strategy}': "+ f"must be one of {sorted(VALID_PRESET_STRATEGIES)}"+ )+ if tmpl["type"] == "script" and strategy not in VALID_SCRIPT_STRATEGIES:+ raise PresetValidationError(+ f"Invalid strategy '{strategy}' for script: "+ f"scripts only support {sorted(VALID_SCRIPT_STRATEGIES)}"+ )++ # Validate template name format+ if tmpl["type"] == "command":+ # Commands use dot notation (e.g. speckit.specify)+ if not re.match(r'^[a-z0-9.-]+$', tmpl["name"]):+ raise PresetValidationError(+ f"Invalid command name '{tmpl['name']}': "+ "must be lowercase alphanumeric with hyphens and dots only"+ )+ else:+ if not re.match(r'^[a-z0-9-]+$', tmpl["name"]):+ raise PresetValidationError(+ f"Invalid template name '{tmpl['name']}': "+ "must be lowercase alphanumeric with hyphens only"+ )++ @property+ def id(self) -> str:+ """Get preset ID."""+ return self.data["preset"]["id"]++ @property+ def name(self) -> str:+ """Get preset name."""+ return self.data["preset"]["name"]++ @property+ def version(self) -> str:+ """Get preset version."""+ return self.data["preset"]["version"]++ @property+ def description(self) -> str:+ """Get preset description."""+ return self.data["preset"]["description"]++ @property+ def author(self) -> str:+ """Get preset author."""+ return self.data["preset"].get("author", "")++ @staticmethod+ def _validate_requires_extensions(declared: Any) -> None:+ """Validate the optional ``requires.extensions`` list.++ Accepts either a bare extension id or a mapping carrying an optional+ version specifier and an optional ``required`` flag:++ .. code-block:: yaml++ requires:+ extensions:+ - speckit-inventory+ - id: other-ext+ version: ">=1.2.0"+ required: false++ Raises:+ PresetValidationError: If the list or any entry is malformed.+ """+ if not isinstance(declared, list):+ raise PresetValidationError(+ "Invalid requires.extensions: expected a list, "+ f"got {type(declared).__name__}"+ )++ for index, entry in enumerate(declared):+ label = f"requires.extensions[{index}]"++ if isinstance(entry, str):+ entry = {"id": entry}+ elif not isinstance(entry, dict):+ raise PresetValidationError(+ f"Invalid {label}: expected a string or a mapping, "+ f"got {type(entry).__name__}"+ )++ if "id" not in entry:+ raise PresetValidationError(f"Missing {label}.id")+ extension_id = entry["id"]+ if not isinstance(extension_id, str):+ raise PresetValidationError(+ f"Invalid {label}.id: expected a string, "+ f"got {type(extension_id).__name__}"+ )+ # Same id shape the extension loader enforces, so a dependency can+ # never name something that could not be installed in the first+ # place. fullmatch rather than match with an anchored pattern: `$`+ # also matches before a trailing newline, so "demo-ext\n" would+ # otherwise validate here while PresetResolver._is_safe_registry_id+ # (which uses fullmatch) rejects it, and the newline would land in+ # a suggested command.+ if not re.fullmatch(r'[a-z0-9-]+', extension_id):+ raise PresetValidationError(+ f"Invalid {label}.id {extension_id!r}: "+ "must be lowercase alphanumeric with hyphens only"+ )++ if "version" in entry:+ constraint = entry["version"]+ # Mirrors the requires.speckit_version reasoning: a non-string+ # escapes InvalidSpecifier two ways -- scalars raise TypeError+ # from the constructor, and a list/dict is iterable so it+ # constructs and only fails later inside .contains().+ if not isinstance(constraint, str) or not constraint.strip():+ raise PresetValidationError(+ f"Invalid {label}.version: expected a non-empty string, "+ f"got {type(constraint).__name__}"+ )+ try:+ SpecifierSet(constraint)+ except InvalidSpecifier:+ raise PresetValidationError(+ f"Invalid {label}.version '{constraint}': "+ "not a valid version specifier"+ )++ if "required" in entry and not isinstance(entry["required"], bool):+ raise PresetValidationError(+ f"Invalid {label}.required: expected a boolean, "+ f"got {type(entry['required']).__name__}"+ )++ @property+ def requires_speckit_version(self) -> str:+ """Get required spec-kit version range."""+ return self.data["requires"]["speckit_version"]++ @property+ def requires_extensions(self) -> List[Dict[str, Any]]:+ """Get declared extension dependencies, normalized to mappings.++ Returns:+ One entry per dependency with ``id``, ``version`` (``None`` when+ unconstrained), and ``required`` (defaulting to ``True``). Empty+ when the manifest declares no dependencies.+ """+ declared = self.data["requires"].get("extensions")+ if not isinstance(declared, list):+ return []++ normalized: List[Dict[str, Any]] = []+ for entry in declared:+ if isinstance(entry, str):+ entry = {"id": entry}+ if not isinstance(entry, dict) or not isinstance(entry.get("id"), str):+ continue+ normalized.append(+ {+ "id": entry["id"],+ "version": entry.get("version"),+ "required": entry.get("required", True),+ }+ )+ return normalized++ @property+ def templates(self) -> List[Dict[str, Any]]:+ """Get list of provided templates."""+ return self.data["provides"]["templates"]++ @property+ def tags(self) -> List[str]:+ """Get preset tags."""+ return self.data.get("tags", [])++ def get_hash(self) -> str:+ """Calculate SHA256 hash of manifest file."""+ h = hashlib.sha256()+ with open(self.path, 'rb') as f:+ for chunk in iter(lambda: f.read(8192), b""):+ h.update(chunk)+ return f"sha256:{h.hexdigest()}"diff --git a/src/specify_cli/presets/_registry.py b/src/specify_cli/presets/_registry.pynew file mode 100644index 000000000..766e7a694--- /dev/null+++ b/src/specify_cli/presets/_registry.py@@ -0,0 +1,245 @@+"""Installed preset registry (private implementation)."""++import copy+import json+from datetime import datetime, timezone+from pathlib import Path+from typing import Dict, List, Optional++from ..extensions import normalize_priority+++class PresetRegistry:+ """Manages the registry of installed presets."""++ REGISTRY_FILE = ".registry"+ SCHEMA_VERSION = "1.0"++ def __init__(self, packs_dir: Path):+ """Initialize registry.++ Args:+ packs_dir: Path to .specify/presets/ directory+ """+ self.packs_dir = packs_dir+ self.registry_path = packs_dir / self.REGISTRY_FILE+ self.data = self._load()++ def _load(self) -> dict:+ """Load registry from disk."""+ if not self.registry_path.exists():+ return {+ "schema_version": self.SCHEMA_VERSION,+ "presets": {}+ }++ try:+ with open(self.registry_path, 'r', encoding='utf-8') as f:+ data = json.load(f)+ # Validate loaded data is a dict (handles corrupted registry files)+ if not isinstance(data, dict):+ return {+ "schema_version": self.SCHEMA_VERSION,+ "presets": {}+ }+ # Normalize presets field (handles corrupted presets value)+ if not isinstance(data.get("presets"), dict):+ data["presets"] = {}+ return data+ except (json.JSONDecodeError, UnicodeDecodeError, FileNotFoundError):+ # Corrupted or missing registry, start fresh. A registry whose+ # bytes cannot be decoded as UTF-8 is the same corruption class+ # as malformed JSON β only the exception type differs. OSError is+ # deliberately not caught: the data may be intact on disk, and+ # starting fresh would let a later _save() wipe it.+ return {+ "schema_version": self.SCHEMA_VERSION,+ "presets": {}+ }++ def _save(self):+ """Save registry to disk."""+ self.packs_dir.mkdir(parents=True, exist_ok=True)+ with open(self.registry_path, 'w', encoding='utf-8') as f:+ json.dump(self.data, f, indent=2)++ def add(self, pack_id: str, metadata: dict):+ """Add preset to registry.++ Args:+ pack_id: Preset ID+ metadata: Pack metadata (version, source, etc.)+ """+ self.data["presets"][pack_id] = {+ **copy.deepcopy(metadata),+ "installed_at": datetime.now(timezone.utc).isoformat()+ }+ self._save()++ def remove(self, pack_id: str):+ """Remove preset from registry.++ Args:+ pack_id: Preset ID+ """+ packs = self.data.get("presets")+ if not isinstance(packs, dict):+ return+ if pack_id in packs:+ del packs[pack_id]+ self._save()++ def update(self, pack_id: str, updates: dict):+ """Update preset metadata in registry.++ Merges the provided updates with the existing entry, preserving any+ fields not specified. The installed_at timestamp is always preserved+ from the original entry.++ Args:+ pack_id: Preset ID+ updates: Partial metadata to merge into existing metadata++ Raises:+ KeyError: If preset is not installed+ """+ packs = self.data.get("presets")+ if not isinstance(packs, dict) or pack_id not in packs:+ raise KeyError(f"Preset '{pack_id}' not found in registry")+ existing = packs[pack_id]+ # Handle corrupted registry entries (e.g., string/list instead of dict)+ if not isinstance(existing, dict):+ existing = {}+ # Merge: existing fields preserved, new fields override (deep copy to prevent caller mutation)+ merged = {**existing, **copy.deepcopy(updates)}+ # Always preserve original installed_at based on key existence, not truthiness,+ # to handle cases where the field exists but may be falsy (legacy/corruption)+ if "installed_at" in existing:+ merged["installed_at"] = existing["installed_at"]+ else:+ # If not present in existing, explicitly remove from merged if caller provided it+ merged.pop("installed_at", None)+ packs[pack_id] = merged+ self._save()++ def restore(self, pack_id: str, metadata: dict):+ """Restore preset metadata to registry without modifying timestamps.++ Use this method for rollback scenarios where you have a complete backup+ of the registry entry (including installed_at) and want to restore it+ exactly as it was.++ Args:+ pack_id: Preset ID+ metadata: Complete preset metadata including installed_at++ Raises:+ ValueError: If metadata is None or not a dict+ """+ if metadata is None or not isinstance(metadata, dict):+ raise ValueError(f"Cannot restore '{pack_id}': metadata must be a dict")+ # Ensure presets dict exists (handle corrupted registry)+ if not isinstance(self.data.get("presets"), dict):+ self.data["presets"] = {}+ self.data["presets"][pack_id] = copy.deepcopy(metadata)+ self._save()++ def get(self, pack_id: str) -> Optional[dict]:+ """Get preset metadata from registry.++ Returns a deep copy to prevent callers from accidentally mutating+ nested internal registry state without going through the write path.++ Args:+ pack_id: Preset ID++ Returns:+ Deep copy of preset metadata, or None if not found or corrupted+ """+ packs = self.data.get("presets")+ if not isinstance(packs, dict):+ return None+ entry = packs.get(pack_id)+ # Return None for missing or corrupted (non-dict) entries+ if entry is None or not isinstance(entry, dict):+ return None+ return copy.deepcopy(entry)++ def list(self) -> Dict[str, dict]:+ """Get all installed presets with valid metadata.++ Returns a deep copy of presets with dict metadata only.+ Corrupted entries (non-dict values) are filtered out.++ Returns:+ Dictionary of pack_id -> metadata (deep copies), empty dict if corrupted+ """+ packs = self.data.get("presets", {}) or {}+ if not isinstance(packs, dict):+ return {}+ # Filter to only valid dict entries to match type contract+ return {+ pack_id: copy.deepcopy(meta)+ for pack_id, meta in packs.items()+ if isinstance(meta, dict)+ }++ def keys(self) -> set:+ """Get all preset IDs including corrupted entries.++ Lightweight method that returns IDs without deep-copying metadata.+ Use this when you only need to check which presets are tracked.++ Returns:+ Set of preset IDs (includes corrupted entries)+ """+ packs = self.data.get("presets", {}) or {}+ if not isinstance(packs, dict):+ return set()+ return set(packs.keys())++ def list_by_priority(self, include_disabled: bool = False) -> List[tuple]:+ """Get all installed presets sorted by priority.++ Lower priority number = higher precedence (checked first).+ Presets with equal priority are sorted alphabetically by ID+ for deterministic ordering.++ Args:+ include_disabled: If True, include disabled presets. Default False.++ Returns:+ List of (pack_id, metadata_copy) tuples sorted by priority.+ Metadata is deep-copied to prevent accidental mutation.+ """+ packs = self.data.get("presets", {}) or {}+ if not isinstance(packs, dict):+ packs = {}+ sortable_packs = []+ for pack_id, meta in packs.items():+ if not isinstance(meta, dict):+ continue+ # Skip disabled presets unless explicitly requested+ if not include_disabled and not meta.get("enabled", True):+ continue+ metadata_copy = copy.deepcopy(meta)+ metadata_copy["priority"] = normalize_priority(metadata_copy.get("priority", 10))+ sortable_packs.append((pack_id, metadata_copy))+ return sorted(+ sortable_packs,+ key=lambda item: (item[1]["priority"], item[0]),+ )++ def is_installed(self, pack_id: str) -> bool:+ """Check if preset is installed.++ Args:+ pack_id: Preset ID++ Returns:+ True if pack is installed, False if not or registry corrupted+ """+ packs = self.data.get("presets")+ if not isinstance(packs, dict):+ return False+ return pack_id in packsdiff --git a/src/specify_cli/presets/_resolver.py b/src/specify_cli/presets/_resolver.pynew file mode 100644index 000000000..ea1c4e03f--- /dev/null+++ b/src/specify_cli/presets/_resolver.py@@ -0,0 +1,949 @@+"""Layered preset and extension resolution (private implementation)."""++import re+from pathlib import Path+from typing import Any, Dict, List, Optional++import yaml++from .._utils import dump_frontmatter+from ..extensions import ExtensionRegistry, normalize_priority+from ._manifest import VALID_PRESET_STRATEGIES, PresetManifest, PresetValidationError+from ._registry import PresetRegistry+++class PresetResolver:+ """Resolves template names to file paths using a priority stack.++ Resolution order:+ 1. .specify/templates/overrides/ - Project-local overrides+ 2. .specify/presets/<preset-id>/ - Installed presets+ 3. .specify/extensions/<ext-id>/templates/ - Extension-provided templates+ 4. .specify/templates/ - Core templates (shipped with Spec Kit)+ """++ def __init__(self, project_root: Path):+ """Initialize preset resolver.++ Args:+ project_root: Path to project root directory+ """+ self.project_root = project_root+ self.templates_dir = project_root / ".specify" / "templates"+ self.presets_dir = project_root / ".specify" / "presets"+ self.overrides_dir = self.templates_dir / "overrides"+ self.extensions_dir = project_root / ".specify" / "extensions"+ self._manifest_cache: Dict[str, Optional["PresetManifest"]] = {}++ def _get_manifest(self, pack_dir: Path) -> Optional["PresetManifest"]:+ """Get a cached preset manifest, parsing it on first access."""+ key = str(pack_dir)+ if key not in self._manifest_cache:+ manifest_path = pack_dir / "preset.yml"+ if manifest_path.exists():+ try:+ self._manifest_cache[key] = PresetManifest(manifest_path)+ except PresetValidationError:+ self._manifest_cache[key] = None+ else:+ self._manifest_cache[key] = None+ return self._manifest_cache[key]++ @staticmethod+ def _is_safe_registry_id(value: object) -> bool:+ return isinstance(value, str) and re.fullmatch(r"[a-z0-9-]+", value) is not None++ def _get_all_presets_by_priority(self) -> List[tuple[str, dict]]:+ registry = PresetRegistry(self.presets_dir)+ return [+ (pack_id, metadata)+ for pack_id, metadata in registry.list_by_priority()+ if self._is_safe_registry_id(pack_id)+ ]++ def _manifest_declared_template(+ self, pack_dir: Path, template_name: str, template_type: str+ ) -> tuple[dict | None, Path | None]:+ """Resolve a preset's manifest-declared template entry and usable file.++ Returns ``(entry, candidate)``:+ - ``entry`` is the matching ``provides.templates`` mapping, or ``None`` if+ the manifest is absent or does not list this ``(name, type)``.+ - ``candidate`` is the declared ``file:`` resolved under ``pack_dir`` IFF+ it is a regular file (``is_file()``); ``None`` otherwise β a missing,+ empty, or non-file (e.g. directory) declaration yields ``(entry, None)``.++ The manifest is authoritative: when it declares a template (``entry`` is+ not ``None``) but the file is unusable (``candidate`` is ``None``),+ callers must NOT fall back to the convention lookup β that would mask a+ typo or pick up an undeclared file. Shared by ``resolve()`` and+ ``collect_all_layers()`` so their manifest-first resolution cannot+ silently diverge again (the divergence this fix addressed).+ """+ manifest = self._get_manifest(pack_dir)+ if not manifest:+ return None, None+ for tmpl in manifest.templates:+ if tmpl.get("name") == template_name and tmpl.get("type") == template_type:+ file_path = tmpl.get("file")+ if file_path:+ manifest_candidate = pack_dir / file_path+ return tmpl, (+ manifest_candidate if manifest_candidate.is_file() else None+ )+ return tmpl, None+ return None, None++ def _extension_manifest_declared_template(+ self, ext_dir: Path, template_name: str, template_type: str+ ) -> tuple[dict | None, Path | None]:+ """Resolve an extension's manifest-declared command/template/script entry and usable file.++ Mirrors ``_manifest_declared_template`` (for presets): returns ``(entry, candidate)``+ where ``entry`` is the matching ``provides.<type>`` mapping, or ``None`` if the+ extension has no (valid) manifest or doesn't declare this ``(name, type)``.+ ``candidate`` is the declared ``file:`` resolved under ``ext_dir`` IFF it is a+ regular file that stays within ``ext_dir`` (guards against path traversal via a+ malformed manifest, mirroring ``resolve_extension_command_via_manifest``);+ ``None`` otherwise.++ The manifest is authoritative: when ``entry`` is not ``None`` but ``candidate`` is+ ``None``, callers must NOT fall back to convention-based lookup β that would mask+ a typo or pick up an undeclared file. Shared by ``resolve()`` and+ ``collect_all_layers()`` so their manifest-first resolution cannot silently+ diverge (the divergence flagged in review on #4012).+ """+ if template_type not in ("command", "template", "script"):+ return None, None+ ext_manifest_path = ext_dir / "extension.yml"+ if not ext_manifest_path.exists():+ return None, None+ from ..extensions import ExtensionManifest+ from ..extensions import ValidationError as ExtValidationError++ try:+ ext_manifest = ExtensionManifest(ext_manifest_path)+ except (ExtValidationError, yaml.YAMLError, OSError, TypeError, AttributeError):+ return None, None+ if template_type == "command":+ entries = ext_manifest.commands+ elif template_type == "template":+ entries = ext_manifest.templates+ else:+ entries = ext_manifest.scripts+ for entry in entries:+ if entry.get("name") != template_name:+ continue+ file_rel = entry.get("file")+ if not file_rel:+ return entry, None+ rel_path = Path(file_rel)+ if rel_path.is_absolute():+ return entry, None+ candidate = ext_dir / rel_path+ try:+ # Resolve only for the containment check, not for the+ # returned path -- resolving the returned path would follow+ # symlinks in ext_dir's ancestors (e.g. a symlinked tmp dir+ # on macOS) and diverge from the unresolved paths convention+ # lookup returns for the same directory.+ candidate.resolve().relative_to(ext_dir.resolve()) # raises ValueError if outside+ except (OSError, ValueError):+ return entry, None+ return entry, (candidate if candidate.is_file() else None)+ return None, None++ def _get_all_extensions_by_priority(self) -> list[tuple[int, str, dict | None]]:+ """Build unified list of registered and unregistered extensions sorted by priority.++ Registered extensions use their stored priority; unregistered directories+ get implicit priority=10. Results are sorted by (priority, ext_id) for+ deterministic ordering.++ Returns:+ List of (priority, ext_id, metadata_or_none) tuples sorted by priority.+ """+ if not self.extensions_dir.exists():+ return []++ registry = ExtensionRegistry(self.extensions_dir)+ # Fail closed on a corrupt registry. ExtensionRegistry._load() recovers+ # by normalizing an unreadable registry to an empty mapping, which would+ # otherwise cause the directory scan below to admit every on-disk+ # directory as an unregistered, enabled extension β a fail-open path+ # that could supply constitution content from an invalid registry state.+ if registry.is_corrupt():+ raise PresetValidationError(+ f"Invalid extension registry {registry.registry_path}: "+ "refusing to enumerate extensions"+ )+ # Use keys() to track ALL extensions (including corrupted entries) without deep copy+ # This prevents corrupted entries from being picked up as "unregistered" dirs+ registered_extension_ids = registry.keys()++ # Get all registered extensions including disabled; we filter disabled manually below+ all_registered = registry.list_by_priority(include_disabled=True)++ all_extensions: list[tuple[int, str, dict | None]] = []++ # Only include enabled extensions in the result+ for ext_id, metadata in all_registered:+ if not self._is_safe_registry_id(ext_id):+ continue+ # Skip disabled extensions+ if not metadata.get("enabled", True):+ continue+ priority = normalize_priority(metadata.get("priority") if metadata else None)+ all_extensions.append((priority, ext_id, metadata))++ # Add unregistered directories with implicit priority=10+ for ext_dir in self.extensions_dir.iterdir():+ if not ext_dir.is_dir() or not self._is_safe_registry_id(ext_dir.name):+ continue+ if ext_dir.name not in registered_extension_ids:+ all_extensions.append((10, ext_dir.name, None))++ # Sort by (priority, ext_id) for deterministic ordering+ all_extensions.sort(key=lambda x: (x[0], x[1]))+ return all_extensions++ @staticmethod+ def _core_stem(template_name: str) -> Optional[str]:+ """Extract the stem for core command lookup.++ Commands use dot notation (e.g. ``speckit.specify``), but core+ command files are named by stem (e.g. ``specify.md``). Returns+ the stem if *template_name* follows the ``speckit.<stem>`` pattern,+ or ``None`` otherwise.+ """+ if template_name.startswith("speckit."):+ return template_name[len("speckit."):]+ return None++ def resolve(+ self,+ template_name: str,+ template_type: str = "template",+ skip_presets: bool = False,+ ) -> Optional[Path]:+ """Resolve a template name to its file path.++ Walks the priority stack and returns the first match.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")+ skip_presets: When True, skip tier 2 (installed presets). Use+ resolve_core() as the preferred caller-facing API for this.++ Returns:+ Path to the resolved template file, or None if not found+ """+ # Determine subdirectory based on template type+ if template_type == "template":+ subdirs = ["templates", ""]+ elif template_type == "command":+ subdirs = ["commands"]+ elif template_type == "script":+ subdirs = ["scripts"]+ else:+ subdirs = [""]++ # Determine file extension based on template type+ ext = ".md"+ if template_type == "script":+ ext = ".sh" # scripts use .sh; callers can also check .ps1++ # Priority 1: Project-local overrides+ if template_type == "script":+ override = self.overrides_dir / "scripts" / f"{template_name}{ext}"+ else:+ override = self.overrides_dir / f"{template_name}{ext}"+ if override.exists():+ return override++ # Priority 2: Installed presets (sorted by priority β lower number wins)+ if not skip_presets and self.presets_dir.exists():+ for pack_id, _metadata in self._get_all_presets_by_priority():+ pack_dir = self.presets_dir / pack_id+ # The preset manifest is authoritative: if it declares this+ # template with an explicit ``file:``, resolve to that path β+ # and do NOT fall back to convention when it's missing, to+ # avoid masking typos or picking up an undeclared file. Only+ # when the manifest is absent or doesn't list this template do+ # we use the convention-based subdir lookup. Mirrors+ # collect_all_layers()/resolve_content() so resolve() and+ # resolve_with_source() agree with them instead of returning+ # the core template (or a stray convention file).+ entry, manifest_candidate = self._manifest_declared_template(+ pack_dir, template_name, template_type+ )+ if manifest_candidate is not None:+ return manifest_candidate+ if entry is not None:+ # Manifest declares this template but the file is missing,+ # non-file (e.g. a directory), or an empty/falsey ``file``+ # value. The manifest is authoritative, so skip this pack's+ # convention fallback rather than mask a typo β mirrors+ # collect_all_layers().+ continue+ for subdir in subdirs:+ if subdir:+ candidate = pack_dir / subdir / f"{template_name}{ext}"+ else:+ candidate = pack_dir / f"{template_name}{ext}"+ if candidate.exists():+ return candidate++ # Priority 3: Extension-provided templates (sorted by priority β lower number wins)+ for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():+ ext_dir = self.extensions_dir / ext_id+ if not ext_dir.is_dir():+ continue+ # The extension manifest is authoritative, same as preset manifests+ # above: check it before convention-based lookup so a declared entry+ # at a non-conventional path wins over a stale conventional file.+ entry, manifest_candidate = self._extension_manifest_declared_template(+ ext_dir, template_name, template_type+ )+ if manifest_candidate is not None:+ return manifest_candidate+ if entry is not None:+ continue+ for subdir in subdirs:+ if subdir:+ candidate = ext_dir / subdir / f"{template_name}{ext}"+ else:+ candidate = ext_dir / f"{template_name}{ext}"+ if candidate.exists():+ return candidate++ # Priority 4: Core templates+ if template_type == "template":+ core = self.templates_dir / f"{template_name}.md"+ if core.exists():+ return core+ elif template_type == "command":+ core = self.templates_dir / "commands" / f"{template_name}.md"+ if core.exists():+ return core+ # Fallback: speckit.<stem> β <stem>.md+ stem = self._core_stem(template_name)+ if stem:+ core = self.templates_dir / "commands" / f"{stem}.md"+ if core.exists():+ return core+ elif template_type == "script":+ core = self.templates_dir / "scripts" / f"{template_name}{ext}"+ if core.exists():+ return core++ # Priority 5: Bundled core_pack (wheel install) or repo-root templates+ # (source-checkout / editable install). This is the canonical home for+ # speckit's built-in command/template files and must always be checked+ # so that strategy:wrap presets can locate {CORE_TEMPLATE}.+ from specify_cli import ( # local import to avoid cycles+ _locate_core_pack,+ _repo_root,+ )+ _core_pack = _locate_core_pack()+ if _core_pack is not None:+ # Wheel install path+ if template_type == "template":+ candidate = _core_pack / "templates" / f"{template_name}.md"+ elif template_type == "command":+ candidate = _core_pack / "commands" / f"{template_name}.md"+ if not candidate.exists():+ stem = self._core_stem(template_name)+ if stem:+ candidate = _core_pack / "commands" / f"{stem}.md"+ elif template_type == "script":+ candidate = _core_pack / "scripts" / f"{template_name}{ext}"+ else:+ candidate = _core_pack / f"{template_name}.md"+ if candidate.exists():+ return candidate+ else:+ # Source-checkout / editable install: templates live at repo root+ repo_root = _repo_root()+ if template_type == "template":+ candidate = repo_root / "templates" / f"{template_name}.md"+ elif template_type == "command":+ candidate = repo_root / "templates" / "commands" / f"{template_name}.md"+ if not candidate.exists():+ stem = self._core_stem(template_name)+ if stem:+ candidate = repo_root / "templates" / "commands" / f"{stem}.md"+ elif template_type == "script":+ candidate = repo_root / "scripts" / f"{template_name}{ext}"+ else:+ candidate = repo_root / f"{template_name}.md"+ if candidate.exists():+ return candidate++ return None++ def resolve_core(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> Optional[Path]:+ """Resolve while skipping installed presets (tier 2).++ Searches tiers 1, 3, 4, and 5 (bundled core_pack / repo-root fallback).+ Use when resolving {CORE_TEMPLATE} to guarantee the result is actual+ base content, never another preset's wrap output.+ """+ return self.resolve(template_name, template_type, skip_presets=True)++ def resolve_extension_command_via_manifest(self, cmd_name: str) -> Optional[Path]:+ """Resolve an extension command by consulting installed extension manifests.++ Walks installed extension directories in priority order, loads each+ extension.yml via ExtensionManifest, and looks up the command by its+ declared name to find the actual file path. This is necessary because+ the manifest's ``provides.commands[].file`` field is authoritative and+ may differ from the command name+ (e.g. ``speckit.selftest.extension`` β ``commands/selftest.md``).++ Returns None if no manifest maps the given command name, so the caller+ can fall back to the name-based lookup.+ """+ if not self.extensions_dir.exists():+ return None++ from ..extensions import ExtensionManifest, ValidationError++ for _priority, ext_id, _metadata in self._get_all_extensions_by_priority():+ ext_dir = self.extensions_dir / ext_id+ manifest_path = ext_dir / "extension.yml"+ if not manifest_path.is_file():+ continue+ try:+ manifest = ExtensionManifest(manifest_path)+ except (ValidationError, OSError, TypeError, AttributeError):+ continue+ for cmd_info in manifest.commands:+ if cmd_info.get("name") != cmd_name:+ continue+ file_rel = cmd_info.get("file")+ if not file_rel:+ continue+ # Mirror the containment check in ExtensionManager to guard against+ # path traversal via a malformed manifest (e.g. file: ../../AGENTS.md).+ cmd_path = Path(file_rel)+ if cmd_path.is_absolute():+ continue+ try:+ ext_root = ext_dir.resolve()+ candidate = (ext_root / cmd_path).resolve()+ candidate.relative_to(ext_root) # raises ValueError if outside+ except (OSError, ValueError):+ continue+ if candidate.is_file():+ return candidate+ return None++ def resolve_with_source(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> Optional[Dict[str, str]]:+ """Resolve a template name and return source attribution.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")++ Returns:+ Dictionary with 'path' and 'source' keys, or None if not found+ """+ # Delegate to resolve() for the actual lookup, then determine source+ resolved = self.resolve(template_name, template_type)+ if resolved is None:+ return None++ resolved_str = str(resolved)++ # Determine source attribution+ if str(self.overrides_dir) in resolved_str:+ return {"path": resolved_str, "source": "project override"}++ if str(self.presets_dir) in resolved_str and self.presets_dir.exists():+ for pack_id, metadata in self._get_all_presets_by_priority():+ pack_dir = self.presets_dir / pack_id+ try:+ resolved.relative_to(pack_dir)+ version = metadata.get("version", "?")+ return {+ "path": resolved_str,+ "source": f"{pack_id} v{version}",+ }+ except ValueError:+ continue++ for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():+ ext_dir = self.extensions_dir / ext_id+ if not ext_dir.is_dir():+ continue+ try:+ resolved.relative_to(ext_dir)+ if ext_meta:+ version = ext_meta.get("version", "?")+ return {+ "path": resolved_str,+ "source": f"extension:{ext_id} v{version}",+ }+ else:+ return {+ "path": resolved_str,+ "source": f"extension:{ext_id} (unregistered)",+ }+ except ValueError:+ continue++ return {"path": resolved_str, "source": "core"}++ def collect_all_layers(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> List[Dict[str, Any]]:+ """Collect all layers in the priority stack for a template.++ Returns layers from highest priority (checked first) to lowest priority.+ Each layer is a dict with 'path', 'source', and 'strategy' keys.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")++ Returns:+ List of layer dicts ordered highest-to-lowest priority.+ """+ if template_type == "template":+ subdirs = ["templates", ""]+ elif template_type == "command":+ subdirs = ["commands"]+ elif template_type == "script":+ subdirs = ["scripts"]+ else:+ subdirs = [""]++ ext = ".md"+ if template_type == "script":+ ext = ".sh"++ layers: List[Dict[str, Any]] = []++ def _find_in_subdirs(base_dir: Path) -> Optional[Path]:+ for subdir in subdirs:+ if subdir:+ candidate = base_dir / subdir / f"{template_name}{ext}"+ else:+ candidate = base_dir / f"{template_name}{ext}"+ if candidate.exists():+ return candidate+ return None++ # Priority 1: Project-local overrides (always "replace" strategy)+ if template_type == "script":+ override = self.overrides_dir / "scripts" / f"{template_name}{ext}"+ else:+ override = self.overrides_dir / f"{template_name}{ext}"+ if override.exists():+ layers.append({+ "path": override,+ "source": "project override",+ "strategy": "replace",+ })++ # Priority 2: Installed presets (sorted by priority β lower number = higher precedence)+ if self.presets_dir.exists():+ for pack_id, metadata in self._get_all_presets_by_priority():+ pack_dir = self.presets_dir / pack_id+ # Read strategy and manifest file path from preset manifest+ strategy = "replace"+ manifest_has_strategy = False+ entry, manifest_candidate = self._manifest_declared_template(+ pack_dir, template_name, template_type+ )+ if entry is not None:+ strategy = entry.get("strategy", "replace")+ manifest_has_strategy = "strategy" in entry+ # Use the manifest's declared file when it's a usable regular file;+ # only fall back to convention-based lookup when the manifest+ # doesn't list this template at all, so preset.yml stays+ # authoritative (a declared-but-unusable file skips convention β+ # parity with resolve()).+ candidate = None+ if manifest_candidate is not None:+ candidate = manifest_candidate+ elif entry is None:+ candidate = _find_in_subdirs(pack_dir)+ if candidate:+ # Legacy fallback: if manifest doesn't explicitly declare a+ # strategy, check the command file's frontmatter for any valid+ # strategy. Skip when the manifest entry includes strategy key+ # (even if it's "replace") to avoid overriding explicit declarations.+ if not manifest_has_strategy and strategy == "replace" and template_type == "command":+ try:+ cmd_content = candidate.read_text(encoding="utf-8")+ lines = cmd_content.splitlines(keepends=True)+ if lines and lines[0].rstrip("\r\n") == "---":+ fence_end = -1+ for fi, fline in enumerate(lines[1:], start=1):+ if fline.rstrip("\r\n") == "---":+ fence_end = fi+ break+ if fence_end > 0:+ fm_text = "".join(lines[1:fence_end])+ fm_data = yaml.safe_load(fm_text)+ if isinstance(fm_data, dict):+ fm_strategy = fm_data.get("strategy")+ if isinstance(fm_strategy, str) and fm_strategy.lower() in VALID_PRESET_STRATEGIES:+ strategy = fm_strategy.lower()+ except (UnicodeDecodeError, yaml.YAMLError, OSError):+ # Best-effort legacy frontmatter parsing: keep default+ # strategy ("replace") when content is unreadable/invalid.+ pass+ version = metadata.get("version", "?") if metadata else "?"+ layers.append({+ "path": candidate,+ "source": f"{pack_id} v{version}",+ "strategy": strategy,+ })++ # Priority 3: Extension-provided templates (always "replace")+ for _priority, ext_id, ext_meta in self._get_all_extensions_by_priority():+ ext_dir = self.extensions_dir / ext_id+ if not ext_dir.is_dir():+ continue+ # The extension manifest is authoritative, same as preset manifests+ # above: check it before convention-based lookup so a declared entry+ # at a non-conventional path wins over a stale conventional file, and+ # a declared-but-missing file isn't silently masked by convention.+ entry, candidate = self._extension_manifest_declared_template(+ ext_dir, template_name, template_type+ )+ if entry is None:+ candidate = _find_in_subdirs(ext_dir)+ if candidate:+ if ext_meta:+ version = ext_meta.get("version", "?")+ source = f"extension:{ext_id} v{version}"+ else:+ source = f"extension:{ext_id} (unregistered)"+ layers.append({+ "path": candidate,+ "source": source,+ "strategy": "replace",+ "extension_id": ext_id,+ "extension_dir": ext_dir,+ })++ # Priority 4: Core templates (always "replace")+ core = None+ if template_type == "template":+ c = self.templates_dir / f"{template_name}.md"+ if c.exists():+ core = c+ elif template_type == "command":+ c = self.templates_dir / "commands" / f"{template_name}.md"+ if c.exists():+ core = c+ else:+ # Fallback: speckit.<stem> β <stem>.md+ stem = self._core_stem(template_name)+ if stem:+ c = self.templates_dir / "commands" / f"{stem}.md"+ if c.exists():+ core = c+ elif template_type == "script":+ c = self.templates_dir / "scripts" / f"{template_name}{ext}"+ if c.exists():+ core = c+ if core:+ layers.append({+ "path": core,+ "source": "core",+ "strategy": "replace",+ })+ else:+ # Priority 5: Bundled core_pack (wheel install) or repo-root+ # templates (source-checkout), matching resolve()'s tier-5 fallback.+ bundled = self._find_bundled_core(template_name, template_type, ext)+ if bundled:+ layers.append({+ "path": bundled,+ "source": "core (bundled)",+ "strategy": "replace",+ })++ return layers++ def _find_bundled_core(+ self,+ template_name: str,+ template_type: str,+ ext: str,+ ) -> Optional[Path]:+ """Find a core template from the bundled pack or source checkout.++ Mirrors the tier-5 fallback logic in ``resolve()`` so that+ ``collect_all_layers()`` can locate base layers even when+ ``.specify/templates/`` doesn't contain the core file.+ """+ try:+ from specify_cli import _locate_core_pack, _repo_root+ except ImportError:+ return None++ stem = self._core_stem(template_name)+ names = [template_name]+ if stem and stem != template_name:+ names.append(stem)++ core_pack = _locate_core_pack()+ if core_pack is not None:+ for name in names:+ if template_type == "template":+ c = core_pack / "templates" / f"{name}.md"+ elif template_type == "command":+ c = core_pack / "commands" / f"{name}.md"+ elif template_type == "script":+ c = core_pack / "scripts" / f"{name}{ext}"+ else:+ c = core_pack / f"{name}.md"+ if c.exists():+ return c+ else:+ repo_root = _repo_root()+ for name in names:+ if template_type == "template":+ c = repo_root / "templates" / f"{name}.md"+ elif template_type == "command":+ c = repo_root / "templates" / "commands" / f"{name}.md"+ elif template_type == "script":+ c = repo_root / "scripts" / f"{name}{ext}"+ else:+ c = repo_root / f"{name}.md"+ if c.exists():+ return c+ return None++ def resolve_content(+ self,+ template_name: str,+ template_type: str = "template",+ ) -> Optional[str]:+ """Resolve a template name and return composed content.++ Walks the priority stack and composes content using strategies:+ - replace (default): highest-priority content wins entirely+ - prepend: content is placed before lower-priority content+ - append: content is placed after lower-priority content+ - wrap: content contains {CORE_TEMPLATE} placeholder replaced+ with lower-priority content (or $CORE_SCRIPT for scripts)++ Composition is recursive β multiple composing presets chain.++ Args:+ template_name: Template name (e.g., "spec-template")+ template_type: Template type ("template", "command", or "script")++ Returns:+ Composed content string, or None if not found+ """+ layers = self.collect_all_layers(template_name, template_type)+ if not layers:+ return None++ def _read_layer_content(layer: Dict[str, Any]) -> Optional[str]:+ """Read a layer's raw text, rewriting extension-relative subdir+ references (agents/, knowledge-base/, etc.) to their installed+ location when the layer is extension-provided (#2101).++ Extension layers are always inserted with strategy "replace"+ (see collect_all_layers), so a layer only ever needs this+ rewrite when it wins outright above or serves as the+ composition base below β never as a mid-stack composing+ (append/prepend/wrap) layer.++ Returns None when the layer cannot be read or decoded:+ collect_all_layers deliberately keeps a non-UTF-8 legacy layer+ (with its "replace" default) so unrelated commands still+ resolve, so the same tolerance must apply here β the documented+ contract is "Composed content string, or None if not found",+ not a raw UnicodeDecodeError at composition time.+ """+ try:+ text = layer["path"].read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ return None+ extension_id = layer.get("extension_id")+ extension_dir = layer.get("extension_dir")+ if extension_id and extension_dir:+ from ..agents import CommandRegistrar++ text = CommandRegistrar.rewrite_extension_paths(+ text, extension_id, extension_dir+ )+ return text++ # If the top (highest-priority) layer is replace, it wins entirely β+ # lower layers are irrelevant regardless of their strategies.+ if layers[0]["strategy"] == "replace":+ return _read_layer_content(layers[0])++ # Composition: build content bottom-up from the effective base.+ # The base is the nearest replace layer scanning from highest priority+ # downward. Only layers above the base contribute to composition.+ #+ # layers is ordered highest-priority first. We process in reverse.+ reversed_layers = list(reversed(layers))++ # Find the effective base: scan from highest priority (layers[0]) downward+ # to find the nearest replace layer. Only compose layers above that base.+ # layers is highest-priority first; reversed_layers is lowest first.+ base_layer_idx = None # index in layers[] (highest-priority first)+ for idx, layer in enumerate(layers):+ if layer["strategy"] == "replace":+ base_layer_idx = idx+ break++ if base_layer_idx is None:+ return None # no replace base found++ # Convert to reversed_layers index+ base_reversed_idx = len(layers) - 1 - base_layer_idx+ content = _read_layer_content(layers[base_layer_idx])+ if content is None:+ return None+ # Compose only the layers above the base (higher priority = lower index in layers,+ # higher index in reversed_layers). Process bottom-up from base+1.+ start_idx = base_reversed_idx + 1++ # For command composition, strip frontmatter from each layer to avoid+ # leaking YAML metadata into the composed body. The highest-priority+ # layer's frontmatter will be reattached at the end.+ is_command = template_type == "command"+ top_frontmatter_text = None+ base_frontmatter_text = None++ def _split_frontmatter(text: str) -> tuple:+ """Return (frontmatter_block_with_fences, body) or (None, text).++ Uses line-based fence detection (fence must be ``---`` on its+ own line) to avoid false matches on ``---`` inside YAML values.+ """+ lines = text.splitlines(keepends=True)+ if not lines or lines[0].rstrip("\r\n") != "---":+ return None, text++ fence_end = -1+ for i, line in enumerate(lines[1:], start=1):+ if line.rstrip("\r\n") == "---":+ fence_end = i+ break++ if fence_end == -1:+ return None, text++ fm_block = "".join(lines[:fence_end + 1]).rstrip("\r\n")+ body = "".join(lines[fence_end + 1:])+ return fm_block, body++ if is_command:+ fm, body = _split_frontmatter(content)+ if fm:+ top_frontmatter_text = fm+ base_frontmatter_text = fm+ content = body++ # Apply composition layers from bottom to top+ for layer in reversed_layers[start_idx:]:+ try:+ layer_content = layer["path"].read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ # Same tolerance as _read_layer_content: an unreadable layer+ # means the composed result cannot be produced.+ return None+ strategy = layer["strategy"]++ if is_command:+ fm, layer_body = _split_frontmatter(layer_content)+ layer_content = layer_body+ # Track the highest-priority frontmatter seen;+ # replace layers reset both top and base frontmatter since+ # they replace the entire command including metadata.+ if strategy == "replace":+ top_frontmatter_text = fm+ base_frontmatter_text = fm+ elif fm:+ top_frontmatter_text = fm++ if strategy == "replace":+ content = layer_content+ elif strategy == "prepend":+ content = layer_content + "\n\n" + content+ elif strategy == "append":+ content = content + "\n\n" + layer_content+ elif strategy == "wrap":+ if template_type == "script":+ placeholder = "$CORE_SCRIPT"+ else:+ placeholder = "{CORE_TEMPLATE}"+ if placeholder not in layer_content:+ raise PresetValidationError(+ f"Wrap strategy in '{layer['source']}' is missing "+ f"the {placeholder} placeholder. The wrapper must "+ f"contain {placeholder} to indicate where the "+ f"lower-priority content should be inserted."+ )+ content = layer_content.replace(placeholder, content)++ # Reattach the highest-priority frontmatter for commands,+ # inheriting scripts/agent_scripts from the base if missing+ # and stripping the strategy key (internal-only, not for agent output).+ if is_command and top_frontmatter_text:+ def _parse_fm_yaml(fm_block: str) -> dict:+ """Parse YAML from a frontmatter block (with --- fences)."""+ lines = fm_block.splitlines()+ # Parse only interior lines (between --- fences)+ if len(lines) >= 2:+ yaml_lines = lines[1:-1]+ else:+ yaml_lines = []+ try:+ return yaml.safe_load("\n".join(yaml_lines)) or {}+ except yaml.YAMLError:+ return {}++ top_fm = _parse_fm_yaml(top_frontmatter_text)++ # Inherit scripts/agent_scripts from base frontmatter if missing+ if base_frontmatter_text and base_frontmatter_text != top_frontmatter_text:+ base_fm = _parse_fm_yaml(base_frontmatter_text)+ for key in ("scripts", "agent_scripts", "argument-hint"):+ if key not in top_fm and key in base_fm:+ top_fm[key] = base_fm[key]++ # Strip strategy key β it's an internal composition directive,+ # not meant for rendered agent command files+ top_fm.pop("strategy", None)++ if top_fm:+ top_frontmatter_text = (+ "---\n"+ + dump_frontmatter(top_fm)+ + "\n---"+ )+ else:+ # Empty frontmatter β omit rather than emitting {}+ top_frontmatter_text = None++ if top_frontmatter_text:+ content = top_frontmatter_text + "\n\n" + content++ return contentdiff --git a/tests/integration/test_preset_update_workflow.py b/tests/integration/test_preset_update_workflow.pyindex 559882282..a0d2e5b8a 100644--- a/tests/integration/test_preset_update_workflow.py+++ b/tests/integration/test_preset_update_workflow.py@@ -1,6 +1,6 @@"""Workflow-level integration tests for ``specify preset update``.-``tests/test_presets.py`` covers the orchestration contract with mocked+``tests/specify_cli/presets/test_command_update.py`` covers the orchestration contract with mocked``preset_remove``/``preset_add`` calls, which proves *what* the wrapper callsbut not that the calls are wired to the real install/remove machinery. Thesetests drive the CLI through ``CliRunner`` against a real project and a realdiff --git a/tests/specify_cli/presets/_helpers.py b/tests/specify_cli/presets/_helpers.pyindex dc3661c05..32cb132ad 100644--- a/tests/specify_cli/presets/_helpers.py+++ b/tests/specify_cli/presets/_helpers.py@@ -126,3 +126,129 @@ def make_convention_constitution_preset(temp_dir: Path) -> Path:))return preset_dir+++class PresetArtifactTestHelpers:+ """Shared setup for preset command, skill, and lifecycle tests."""++ def _write_init_options(self, project_dir, ai="claude", ai_skills=True, script="sh"):+ from specify_cli import save_init_options++ save_init_options(project_dir, {"ai": ai, "ai_skills": ai_skills, "script": script})++ def _create_skill(self, skills_dir, skill_name, body="original body"):+ skill_dir = skills_dir / skill_name+ skill_dir.mkdir(parents=True, exist_ok=True)+ (skill_dir / "SKILL.md").write_text(+ f"---\nname: {skill_name}\n---\n\n{body}\n"+ )+ return skill_dir++ def _create_command_preset(self, temp_dir, preset_id, command_name, description, body):+ preset_dir = temp_dir / preset_id+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ command_file = f"{command_name}.md"+ (preset_dir / "commands" / command_file).write_text(+ f"---\ndescription: {description}\n---\n\n{body}\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": preset_id,+ "name": preset_id,+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": command_name,+ "file": f"commands/{command_file}",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)+ return preset_dir++ def _create_multi_command_preset(self, temp_dir, preset_id, command_names):+ """Install-directory helper for a preset with more than one command.++ Used to prove partial-result handling: a command's own template+ entry can genuinely be skipped by registration (missing source+ file, safety-validation rejection) while sibling commands in the+ same preset still succeed.+ """+ preset_dir = temp_dir / preset_id+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ templates = []+ for command_name in command_names:+ command_file = f"{command_name}.md"+ (preset_dir / "commands" / command_file).write_text(+ f"---\ndescription: {command_name} test command\n---\n\n"+ f"{command_name} body\n"+ )+ templates.append({+ "type": "command",+ "name": command_name,+ "file": f"commands/{command_file}",+ })+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": preset_id,+ "name": preset_id,+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {"templates": templates},+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)+ return preset_dir++ def _create_multi_command_preset_with_aliases(self, temp_dir, preset_id, command_specs):+ """Install-directory helper for a preset whose commands carry aliases.++ ``command_specs`` is a list of ``(primary_name, [alias, ...])``+ tuples. Each command gets its own source file (aliases share the+ same source/content as their primary β CommandRegistrar renders+ them from the same command file, just under a different output+ name (#2948)).+ """+ preset_dir = temp_dir / preset_id+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ templates = []+ for primary_name, aliases in command_specs:+ command_file = f"{primary_name}.md"+ (preset_dir / "commands" / command_file).write_text(+ f"---\ndescription: {primary_name} test command\n---\n\n"+ f"{primary_name} body\n"+ )+ templates.append({+ "type": "command",+ "name": primary_name,+ "file": f"commands/{command_file}",+ "aliases": list(aliases),+ })+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": preset_id,+ "name": preset_id,+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {"templates": templates},+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)+ return preset_dirdiff --git a/tests/specify_cli/presets/conftest.py b/tests/specify_cli/presets/conftest.pyindex e8cdb4f34..9fa00b4c1 100644--- a/tests/specify_cli/presets/conftest.py+++ b/tests/specify_cli/presets/conftest.py@@ -1,4 +1,4 @@-"""Load shared fixtures for mirrored preset command tests."""+"""Load shared fixtures for mirrored preset domain and command tests."""from __future__ import annotationsdiff --git a/tests/specify_cli/presets/test_catalog.py b/tests/specify_cli/presets/test_catalog.pynew file mode 100644index 000000000..2ffbddfed--- /dev/null+++ b/tests/specify_cli/presets/test_catalog.py@@ -0,0 +1,1668 @@+"""Tests for preset discovery and downloads in specify_cli.presets._catalog."""++import io+import json+import tarfile+import zipfile+from contextlib import contextmanager+from datetime import datetime, timezone+from pathlib import Path+from unittest.mock import MagicMock++import pytest+import yaml++from specify_cli.presets import (+ PresetCatalog,+ PresetCatalogEntry,+ PresetError,+ PresetValidationError,+)+++class TestPresetCatalog:+ """Test template catalog functionality."""++ def _inject_github_config(self, monkeypatch, token_env="GH_TOKEN"):+ from tests.specify_cli.authentication.helpers import inject_github_config+ inject_github_config(monkeypatch, token_env)++ def test_default_catalog_url(self, project_dir):+ """Test default catalog URL."""+ catalog = PresetCatalog(project_dir)+ assert catalog.DEFAULT_CATALOG_URL.startswith("https://")+ assert catalog.DEFAULT_CATALOG_URL.endswith("/presets/catalog.json")++ def test_community_catalog_url(self, project_dir):+ """Test community catalog URL."""+ catalog = PresetCatalog(project_dir)+ assert "presets/catalog.community.json" in catalog.COMMUNITY_CATALOG_URL++ def test_cache_validation_no_cache(self, project_dir):+ """Test cache validation when no cache exists."""+ catalog = PresetCatalog(project_dir)+ assert catalog.is_cache_valid() is False++ def test_cache_validation_valid(self, project_dir):+ """Test cache validation with valid cache."""+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)++ catalog.cache_file.write_text(json.dumps({+ "schema_version": "1.0",+ "presets": {},+ }))+ catalog.cache_metadata_file.write_text(json.dumps({+ "cached_at": datetime.now(timezone.utc).isoformat(),+ }))++ assert catalog.is_cache_valid() is True++ def test_cache_validation_expired(self, project_dir):+ """Test cache validation with expired cache."""+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)++ catalog.cache_file.write_text(json.dumps({+ "schema_version": "1.0",+ "presets": {},+ }))+ catalog.cache_metadata_file.write_text(json.dumps({+ "cached_at": "2020-01-01T00:00:00+00:00",+ }))++ assert catalog.is_cache_valid() is False++ def test_cache_validation_corrupted(self, project_dir):+ """Test cache validation with corrupted metadata."""+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)++ catalog.cache_file.write_text("not json")+ catalog.cache_metadata_file.write_text("not json")++ assert catalog.is_cache_valid() is False++ def test_clear_cache(self, project_dir):+ """Test clearing the cache."""+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ catalog.cache_file.write_text("{}")+ catalog.cache_metadata_file.write_text("{}")++ catalog.clear_cache()++ assert not catalog.cache_file.exists()+ assert not catalog.cache_metadata_file.exists()++ def test_search_with_cached_data(self, project_dir, monkeypatch):+ """Test search with cached catalog data."""+ from unittest.mock import patch++ monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL", raising=False)+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)++ catalog_data = {+ "schema_version": "1.0",+ "presets": {+ "safe-agile": {+ "name": "SAFe Agile Templates",+ "description": "SAFe-aligned templates",+ "author": "agile-community",+ "version": "1.0.0",+ "tags": ["safe", "agile"],+ },+ "healthcare": {+ "name": "Healthcare Compliance",+ "description": "HIPAA-compliant templates",+ "author": "healthcare-org",+ "version": "1.0.0",+ "tags": ["healthcare", "hipaa"],+ },+ }+ }++ catalog.cache_file.write_text(json.dumps(catalog_data))+ catalog.cache_metadata_file.write_text(json.dumps({+ "cached_at": datetime.now(timezone.utc).isoformat(),+ }))++ # Isolate from community catalog so results are deterministic+ default_only = [PresetCatalogEntry(url=catalog.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True)]+ with patch.object(catalog, "get_active_catalogs", return_value=default_only):+ # Search by query+ results = catalog.search(query="agile")+ assert len(results) == 1+ assert results[0]["id"] == "safe-agile"++ # Search by tag+ results = catalog.search(tag="hipaa")+ assert len(results) == 1+ assert results[0]["id"] == "healthcare"++ # Search by author+ results = catalog.search(author="agile-community")+ assert len(results) == 1++ # Search all+ results = catalog.search()+ assert len(results) == 2++ def test_get_pack_info(self, project_dir):+ """Test getting info for a specific pack."""+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)++ catalog_data = {+ "schema_version": "1.0",+ "presets": {+ "test-pack": {+ "name": "Test Pack",+ "version": "1.0.0",+ },+ }+ }++ catalog.cache_file.write_text(json.dumps(catalog_data))+ catalog.cache_metadata_file.write_text(json.dumps({+ "cached_at": datetime.now(timezone.utc).isoformat(),+ }))++ info = catalog.get_pack_info("test-pack")+ assert info is not None+ assert info["name"] == "Test Pack"+ assert info["id"] == "test-pack"++ assert catalog.get_pack_info("nonexistent") is None++ def test_validate_catalog_url_https(self, project_dir):+ """Test that HTTPS URLs are accepted."""+ catalog = PresetCatalog(project_dir)+ catalog._validate_catalog_url("https://example.com/catalog.json")++ def test_validate_catalog_url_http_rejected(self, project_dir):+ """Test that HTTP URLs are rejected."""+ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="must use HTTPS"):+ catalog._validate_catalog_url("http://example.com/catalog.json")++ def test_validate_catalog_url_localhost_http_allowed(self, project_dir):+ """Test that HTTP is allowed for localhost."""+ catalog = PresetCatalog(project_dir)+ catalog._validate_catalog_url("http://localhost:8080/catalog.json")+ catalog._validate_catalog_url("http://127.0.0.1:8080/catalog.json")++ @pytest.mark.parametrize(+ "url",+ [+ "https://:8080", # port only, no host+ "https://:8080/catalog.json", # port only, with path+ "https://:0", # port only, no host+ "https://user@", # userinfo only, no host+ "https://user:pass@", # userinfo only, no host+ ],+ )+ def test_validate_catalog_url_hostless_rejected(self, project_dir, url):+ """Reject host-less URLs whose netloc is truthy but hostname is None (#3209).++ ``urlparse('https://:8080').netloc`` is ``':8080'`` (truthy) but its+ ``hostname`` is ``None``, so a netloc-based check would accept a URL+ with no actual host, contradicting the "valid URL with a host" error.+ """+ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="valid URL with a host"):+ catalog._validate_catalog_url(url)++ def test_validate_catalog_url_malformed_rejected(self, project_dir):+ """A malformed URL raises PresetValidationError, not a raw ValueError.++ ``urlparse('https://[::1').hostname`` raises ``ValueError: Invalid IPv6+ URL`` (unterminated bracket). Without wrapping, that leaks past callers'+ ``except PresetValidationError`` guards and crashes the CLI. Mirrors the+ shared ``CatalogStackBase`` (#3435) and ``IntegrationCatalog`` behaviour.+ """+ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="malformed"):+ catalog._validate_catalog_url("https://[::1")++ def test_validate_catalog_url_out_of_range_port_rejected(self, project_dir):+ """An out-of-range port raises ValueError lazily on ``.port`` access.++ ``urlparse(...).hostname`` alone does not validate the port, so+ without a ``_ = parsed.port`` probe inside the try/except, a URL like+ ``https://example.com:99999/catalog.json`` sails through this+ validator and only fails later, at fetch time, with a raw+ untranslated error instead of a clean ``PresetValidationError``. The+ sibling ``preset add --from <url>`` download-URL guard already+ catches this shape (see+ ``test_preset_add_from_url_out_of_range_port_exits_cleanly``); this+ catalog-source-URL validator had drifted from it and from the+ original guard in ``specify_cli.catalogs``/+ ``bundler/services/adapters.py``.+ """+ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="malformed"):+ catalog._validate_catalog_url("https://example.com:99999/catalog.json")++ def test_env_var_catalog_url(self, project_dir, monkeypatch):+ """Test catalog URL from environment variable."""+ monkeypatch.setenv("SPECKIT_PRESET_CATALOG_URL", "https://custom.example.com/catalog.json")+ catalog = PresetCatalog(project_dir)+ assert catalog.get_catalog_url() == "https://custom.example.com/catalog.json"++ # --- _make_request / GitHub auth ---++ def test_make_request_no_token_no_auth_header(self, project_dir, monkeypatch):+ """Without a token, requests carry no Authorization header."""+ monkeypatch.delenv("GITHUB_TOKEN", raising=False)+ monkeypatch.delenv("GH_TOKEN", raising=False)+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")+ assert "Authorization" not in req.headers++ def test_make_request_whitespace_only_github_token_ignored(self, project_dir, monkeypatch):+ """A whitespace-only GITHUB_TOKEN is treated as unset."""+ monkeypatch.setenv("GITHUB_TOKEN", " ")+ monkeypatch.delenv("GH_TOKEN", raising=False)+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")+ assert "Authorization" not in req.headers++ def test_make_request_whitespace_github_token_falls_back_to_gh_token(self, project_dir, monkeypatch):+ """When GITHUB_TOKEN is whitespace-only, GH_TOKEN is used as fallback."""+ monkeypatch.setenv("GITHUB_TOKEN", " ")+ monkeypatch.setenv("GH_TOKEN", "ghp_fallback")+ self._inject_github_config(monkeypatch, token_env="GH_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")+ assert req.get_header("Authorization") == "Bearer ghp_fallback"++ def test_make_request_github_token_added_for_github_url(self, project_dir, monkeypatch):+ """GITHUB_TOKEN is attached for raw.githubusercontent.com URLs."""+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ monkeypatch.delenv("GH_TOKEN", raising=False)+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")+ assert req.get_header("Authorization") == "Bearer ghp_testtoken"++ def test_make_request_gh_token_fallback(self, project_dir, monkeypatch):+ """GH_TOKEN is used when GITHUB_TOKEN is absent."""+ monkeypatch.delenv("GITHUB_TOKEN", raising=False)+ monkeypatch.setenv("GH_TOKEN", "ghp_ghtoken")+ self._inject_github_config(monkeypatch, token_env="GH_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://github.com/org/repo/releases/download/v1/pack.zip")+ assert req.get_header("Authorization") == "Bearer ghp_ghtoken"++ def test_make_request_gh_token_takes_precedence(self, project_dir, monkeypatch):+ """When auth.json uses GH_TOKEN, that token is used regardless of GITHUB_TOKEN."""+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_secondary")+ monkeypatch.setenv("GH_TOKEN", "ghp_primary")+ self._inject_github_config(monkeypatch, token_env="GH_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://api.github.com/repos/org/repo")+ assert req.get_header("Authorization") == "Bearer ghp_primary"++ def test_make_request_token_added_for_codeload_github_com(self, project_dir, monkeypatch):+ """GITHUB_TOKEN is attached for codeload.github.com URLs."""+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://codeload.github.com/org/repo/zip/refs/tags/v1.0.0")+ assert req.get_header("Authorization") == "Bearer ghp_testtoken"++ def test_make_request_no_auth_for_non_matching_host(self, project_dir, monkeypatch):+ """Auth is NOT attached to hosts not listed in auth.json."""+ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://internal.example.com/catalog.json")+ assert "Authorization" not in req.headers++ def test_make_request_no_auth_when_no_config(self, project_dir, monkeypatch):+ """No auth header when no auth.json config exists."""+ monkeypatch.delenv("GITHUB_TOKEN", raising=False)+ monkeypatch.delenv("GH_TOKEN", raising=False)+ catalog = PresetCatalog(project_dir)+ req = catalog._make_request("https://github.com/org/repo/releases/download/v1/pack.zip")+ assert "Authorization" not in req.headers++ def test_fetch_single_catalog_sends_auth_header(self, project_dir, monkeypatch):+ """_fetch_single_catalog passes Authorization header when configured."""+ from unittest.mock import patch, MagicMock++ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)++ catalog_data = {"schema_version": "1.0", "presets": {}}+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(catalog_data).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://raw.githubusercontent.com/org/repo/main/presets/catalog.json"++ captured = {}+ mock_opener = MagicMock()++ def fake_open(req, timeout=None):+ captured["req"] = req+ return mock_response++ mock_opener.open.side_effect = fake_open++ entry = PresetCatalogEntry(+ url="https://raw.githubusercontent.com/org/repo/main/presets/catalog.json",+ name="private",+ priority=1,+ install_allowed=True,+ )++ with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):+ catalog._fetch_single_catalog(entry, force_refresh=True)++ assert captured["req"].get_header("Authorization") == "Bearer ghp_testtoken"++ def test_fetch_single_catalog_revalidates_redirected_url(self, project_dir):+ """An HTTPS catalog URL that redirects to http:// must be rejected AFTER+ the redirect. _open_url follows redirects (auth stripped on downgrade),+ so without re-validating response.geturl() the http payload would still+ be fetched and trusted β and it supplies each preset's download_url ++ sha256, defeating verify_archive_sha256. Parity with the+ integrations/workflows catalog fetchers."""+ catalog = PresetCatalog(project_dir)++ class _Resp:+ def __enter__(self):+ return self++ def __exit__(self, *a):+ return False++ def read(self):+ return json.dumps({"schema_version": "1.0", "presets": {}}).encode()++ def geturl(self):+ return "http://evil.test/catalog.json" # downgraded via redirect++ catalog._open_url = lambda url, timeout=None, redirect_validator=None: _Resp()++ entry = PresetCatalogEntry(+ url="https://good.example/catalog.json",+ name="c",+ priority=1,+ install_allowed=True,+ )+ with pytest.raises(PresetValidationError, match="HTTPS"):+ catalog._fetch_single_catalog(entry, force_refresh=True)++ def test_fetch_single_catalog_validates_every_redirect_hop(self, project_dir):+ """A redirect_validator is passed to _open_url and rejects a non-HTTPS+ INTERMEDIATE hop β closing the https -> http -> attacker-https chain that+ a terminal-URL-only check would miss."""+ catalog = PresetCatalog(project_dir)+ captured = {}++ def fake_open(url, timeout=None, redirect_validator=None):+ captured["rv"] = redirect_validator+ # Simulate the hop urllib validates before following the redirect.+ redirect_validator("https://good.example/catalog.json", "http://evil.test/hop")+ raise AssertionError("redirect_validator should have raised")++ catalog._open_url = fake_open+ entry = PresetCatalogEntry(+ url="https://good.example/catalog.json",+ name="c",+ priority=1,+ install_allowed=True,+ )+ with pytest.raises(PresetValidationError, match="HTTPS"):+ catalog._fetch_single_catalog(entry, force_refresh=True)+ assert captured["rv"] is not None++ def test_fetch_catalog_legacy_revalidates_redirected_url(self, project_dir):+ """The legacy single-catalog fetch_catalog() path also rejects an+ HTTPS -> http redirected payload (final geturl() check), matching+ _fetch_single_catalog β it previously parsed the body with no check."""+ catalog = PresetCatalog(project_dir)++ class _Resp:+ def __enter__(self):+ return self++ def __exit__(self, *a):+ return False++ def read(self):+ return json.dumps({"schema_version": "1.0", "presets": {}}).encode()++ def geturl(self):+ return "http://evil.test/catalog.json"++ catalog._open_url = lambda url, timeout=None, redirect_validator=None: _Resp()+ with pytest.raises(PresetError, match="HTTPS"):+ catalog.fetch_catalog(force_refresh=True)++ def test_fetch_catalog_legacy_validates_every_redirect_hop(self, project_dir):+ """The legacy fetch_catalog() path also validates every INTERMEDIATE hop+ (not just the terminal URL): it must supply a redirect_validator that+ rejects an insecure hop, so an https -> http -> https chain is caught."""+ catalog = PresetCatalog(project_dir)+ captured = {}++ def fake_open(url, timeout=None, redirect_validator=None):+ captured["rv"] = redirect_validator+ redirect_validator(url, "http://evil.test/hop")+ raise AssertionError("redirect_validator should have raised")++ catalog._open_url = fake_open+ with pytest.raises(PresetError, match="HTTPS"):+ catalog.fetch_catalog(force_refresh=True)+ assert captured["rv"] is not None++ @pytest.mark.parametrize(+ "payload",+ [+ # Root is not a JSON object.+ [],+ "oops",+ 42,+ None,+ # Root is fine but ``presets`` is the wrong type.+ {"schema_version": "1.0", "presets": []},+ {"schema_version": "1.0", "presets": "oops"},+ {"schema_version": "1.0", "presets": None},+ {"schema_version": "1.0", "presets": 42},+ ],+ )+ def test_fetch_single_catalog_rejects_malformed_payload(self, project_dir, payload):+ """Malformed catalog payloads raise PresetError, not AttributeError.++ Without this guard, a payload like ``{"presets": []}`` would pass the+ key-presence check and then crash with ``AttributeError: 'list' object+ has no attribute 'items'`` deep inside ``_get_merged_packs``. The+ sibling integration catalog reader already validates both the root+ object and the nested mapping (see ``integrations/catalog.py``); the+ preset catalog must stay consistent.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)++ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ # A real urllib response reports the final URL (== request URL with no+ # redirect); the fetcher re-validates it after redirects.+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ entry = PresetCatalogEntry(+ url="https://example.com/catalog.json",+ name="default",+ priority=1,+ install_allowed=True,+ )++ with patch.object(catalog, "_open_url", return_value=mock_response):+ with pytest.raises(PresetError, match="Invalid preset catalog format"):+ catalog._fetch_single_catalog(entry, force_refresh=True)++ @pytest.mark.parametrize(+ "cached_payload",+ [+ [],+ "oops",+ 42,+ None,+ {"schema_version": "1.0", "presets": []},+ {"schema_version": "1.0", "presets": "oops"},+ {"schema_version": "1.0", "presets": None},+ ],+ )+ def test_fetch_single_catalog_rejects_malformed_cached_payload(+ self, project_dir, cached_payload+ ):+ """A poisoned cache silently falls back to the network instead of+ crashing β cached payloads pass through the same shape validation+ as freshly-fetched ones.++ Without this, a cache poisoned by an older spec-kit version (or a+ manual edit, or an upstream that briefly served a bad payload+ before the network guards landed) would re-crash every invocation+ of ``_get_merged_packs`` despite the cache being "valid" by age.+ The recovery contract is: if the cached payload fails validation,+ drop it and refetch β never propagate ``AttributeError`` to the+ caller.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)++ # Poison the default-URL cache. ``DEFAULT_CATALOG_URL`` and+ # non-default URLs both flow through the same cache-load branch.+ cache_file, metadata_file = catalog._get_cache_paths(+ catalog.DEFAULT_CATALOG_URL+ )+ cache_file.parent.mkdir(parents=True, exist_ok=True)+ cache_file.write_text(json.dumps(cached_payload))+ metadata_file.write_text(+ json.dumps(+ {+ "cached_at": datetime.now(timezone.utc).isoformat(),+ "catalog_url": catalog.DEFAULT_CATALOG_URL,+ }+ )+ )++ # Network refetch returns a valid payload so the recovery path+ # can complete.+ valid = {+ "schema_version": "1.0",+ "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},+ }+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = catalog.DEFAULT_CATALOG_URL++ entry = PresetCatalogEntry(+ url=catalog.DEFAULT_CATALOG_URL,+ name="default",+ priority=1,+ install_allowed=True,+ )++ with patch.object(catalog, "_open_url", return_value=mock_response):+ result = catalog._fetch_single_catalog(entry, force_refresh=False)++ # The poisoned cache was discarded and the network payload returned.+ assert result == valid++ @pytest.mark.parametrize(+ "payload",+ [+ # Root is not a JSON object.+ [],+ "oops",+ 42,+ None,+ # Root is fine but ``presets`` is the wrong type.+ {"schema_version": "1.0", "presets": []},+ {"schema_version": "1.0", "presets": "oops"},+ {"schema_version": "1.0", "presets": None},+ ],+ )+ def test_fetch_catalog_rejects_malformed_payload(self, project_dir, payload):+ """Legacy ``fetch_catalog`` reuses the same shape-validation helper.++ Before this change ``fetch_catalog`` only checked key presence β+ so a payload like ``42`` would crash with+ ``TypeError: argument of type 'int' is not iterable`` during the+ ``"schema_version" in catalog_data`` check, and an entry mapping+ of the wrong type would crash downstream. Reusing+ ``_validate_catalog_payload`` keeps the network-side behaviour of+ the legacy single-catalog method consistent with the multi-catalog+ ``_fetch_single_catalog`` path.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ with patch.object(catalog, "_open_url", return_value=mock_response):+ with pytest.raises(PresetError, match="Invalid preset catalog format"):+ catalog.fetch_catalog(force_refresh=True)++ def test_fetch_catalog_recovers_from_unreadable_cache(self, project_dir):+ """An unreadable / wrong-encoded cache file silently refetches.++ The cache contract is best-effort: a JSON-decode failure, an OS+ read failure (permissions / disk / handle limit), or an invalid+ text encoding on a cache file written by an older client must+ all fall through to the network fetch rather than crash the+ caller. Covers Copilot's review point that the previous+ ``except (json.JSONDecodeError, OSError)`` was missing+ ``UnicodeError``.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ # Invalid UTF-8 bytes so ``read_text`` raises ``UnicodeDecodeError``+ # (a subclass of ``UnicodeError``).+ catalog.cache_file.write_bytes(b"\xff\xfe\x00not-utf-8")+ catalog.cache_metadata_file.write_text(+ json.dumps(+ {+ "cached_at": datetime.now(timezone.utc).isoformat(),+ "catalog_url": catalog.get_catalog_url(),+ }+ ),+ encoding="utf-8",+ )++ valid = {+ "schema_version": "1.0",+ "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},+ }+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ with patch.object(catalog, "_open_url", return_value=mock_response):+ result = catalog.fetch_catalog(force_refresh=False)++ # Recovered via network rather than crashing on the unreadable cache.+ assert result == valid++ def test_fetch_catalog_recovers_from_unreadable_metadata(self, project_dir):+ """A wrongly-encoded metadata file degrades to a cache miss.++ ``is_cache_valid`` is consulted *before* the cache payload is+ read; if the metadata file itself can't be decoded (e.g. it was+ written on a host whose default codec isn't UTF-8) the validity+ check must return ``False`` rather than propagate+ ``UnicodeDecodeError``. Without that guard, a corrupted metadata+ file would crash every invocation instead of falling through to+ a network refetch.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ catalog.cache_file.write_text("{}", encoding="utf-8")+ # Bytes that are not valid UTF-8 β ``read_text(encoding="utf-8")``+ # will raise ``UnicodeDecodeError`` (subclass of ``UnicodeError``).+ catalog.cache_metadata_file.write_bytes(b"\xff\xfe\x00bad")++ # is_cache_valid must absorb the decode failure, not crash.+ assert catalog.is_cache_valid() is False++ valid = {+ "schema_version": "1.0",+ "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},+ }+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ with patch.object(catalog, "_open_url", return_value=mock_response):+ result = catalog.fetch_catalog(force_refresh=False)++ assert result == valid++ @pytest.mark.parametrize(+ "non_mapping_metadata",+ [+ "[]", # JSON array+ '"oops"', # JSON string+ "42", # JSON number+ "true", # JSON bool+ "null", # JSON null+ ],+ )+ def test_is_cache_valid_handles_non_mapping_metadata(+ self, project_dir, non_mapping_metadata+ ):+ """Metadata that parses to a non-mapping degrades to cache-invalid.++ The cache-validity check calls ``metadata.get("cached_at", "")``+ immediately after ``json.loads``. If the metadata file is valid+ JSON but parses to a non-mapping (``[]``, ``"oops"``, ``42``,+ ``true``, ``null``), ``.get`` raises ``AttributeError`` β which+ previously slipped past the except tuple and crashed the+ caller. The contract documented on ``is_cache_valid`` says any+ decode/shape failure should return ``False`` so ``fetch_catalog``+ falls through to a network refetch. This test pins that+ contract across every JSON non-mapping root type.+ """+ catalog = PresetCatalog(project_dir)+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ catalog.cache_file.write_text("{}", encoding="utf-8")+ catalog.cache_metadata_file.write_text(+ non_mapping_metadata, encoding="utf-8"+ )++ # Must not raise β the contract is "any decode/shape failure β False".+ assert catalog.is_cache_valid() is False++ def test_fetch_catalog_writes_cache_as_utf8(self, project_dir, monkeypatch):+ """Cache + metadata writes pass ``encoding="utf-8"``, observably.++ The earlier version of this test claimed to assert UTF-8 at the+ byte level but actually only round-tripped a non-ASCII string+ through ``json.dumps`` and ``read_text(encoding="utf-8")``.+ Because ``json.dumps`` defaults to ``ensure_ascii=True``, "cafΓ©"+ was serialized as the all-ASCII escape ``caf\\u00e9`` before it+ ever reached ``write_text`` β the bytes on disk were identical+ regardless of the encoding kwarg. The drift Copilot's review+ flagged wasn't actually being caught.++ Fix: directly observe the ``encoding`` argument passed to every+ ``write_text`` call made against the cache directory. This is+ the production code's encoding choice, which is exactly what+ the regression guard cares about.+ """+ from unittest.mock import patch, MagicMock+ from pathlib import Path as _PathCls++ catalog = PresetCatalog(project_dir)+ payload = {+ "schema_version": "1.0",+ "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},+ }+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode("utf-8")).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ # Record every ``write_text`` call's encoding kwarg so the+ # assertion observes the production writer's argument directly.+ recorded: list[dict] = []+ real_write_text = _PathCls.write_text++ def recording_write_text(self, data, *args, **kwargs):+ recorded.append(+ {"path": str(self), "encoding": kwargs.get("encoding")}+ )+ return real_write_text(self, data, *args, **kwargs)++ monkeypatch.setattr(_PathCls, "write_text", recording_write_text)++ with patch.object(catalog, "_open_url", return_value=mock_response):+ catalog.fetch_catalog(force_refresh=True)++ cache_writes = [+ r for r in recorded if str(catalog.cache_dir) in r["path"]+ ]+ assert cache_writes, "fetch_catalog made no writes to the cache dir"+ for record in cache_writes:+ assert record["encoding"] == "utf-8", (+ f"write_text on {record['path']} used encoding "+ f"{record['encoding']!r}; expected 'utf-8'"+ )++ def test_fetch_catalog_survives_unwritable_cache(self, project_dir, monkeypatch):+ """An unwritable cache dir doesn't fail a successful fetch.++ Cache writes are best-effort, mirroring the read side and the+ ``integrations/catalog.py`` precedent: if ``mkdir``/``write_text``+ raises ``OSError`` (read-only checkout, permissions), the+ already-fetched-and-validated payload must still be returned β+ not swallowed into the broad except and re-raised as a+ ``PresetError``.+ """+ from unittest.mock import patch, MagicMock+ from pathlib import Path as _PathCls++ catalog = PresetCatalog(project_dir)+ valid = {+ "schema_version": "1.0",+ "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},+ }+ def make_response():+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = catalog.DEFAULT_CATALOG_URL+ return mock_response++ # Simulate an unwritable cache dir: every write_text under the+ # cache directory raises PermissionError (an OSError subclass).+ real_write_text = _PathCls.write_text++ def failing_write_text(self, data, *args, **kwargs):+ if str(catalog.cache_dir) in str(self):+ raise PermissionError("cache dir is read-only")+ return real_write_text(self, data, *args, **kwargs)++ monkeypatch.setattr(_PathCls, "write_text", failing_write_text)++ with patch.object(catalog, "_open_url", side_effect=lambda *a, **kw: make_response()):+ # Legacy single-catalog path.+ assert catalog.fetch_catalog(force_refresh=True) == valid++ # Multi-catalog path.+ entry = PresetCatalogEntry(+ url=catalog.DEFAULT_CATALOG_URL,+ name="default",+ priority=1,+ install_allowed=True,+ )+ assert (+ catalog._fetch_single_catalog(entry, force_refresh=True) == valid+ )++ def test_get_merged_packs_skips_non_mapping_entries(self, project_dir):+ """Per-entry guard: one malformed entry shouldn't poison the merge.++ ``_fetch_single_catalog`` validates that ``presets`` is a mapping,+ but it doesn't (and shouldn't) validate every entry inside it β a+ single bad entry in an otherwise-valid catalog should be skipped,+ not crash the whole resolve path. Mirrors the per-entry skip in+ ``integrations/catalog.py``: a malformed entry returns no error,+ valid entries continue to merge normally.+ """+ from unittest.mock import patch, MagicMock++ catalog = PresetCatalog(project_dir)+ payload = {+ "schema_version": "1.0",+ "presets": {+ "good": {"name": "Good", "version": "1.0.0"},+ "bad-list": [],+ "bad-str": "oops",+ },+ }+ mock_response = MagicMock()+ mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read+ mock_response.__enter__ = lambda s: s+ mock_response.__exit__ = MagicMock(return_value=False)+ mock_response.geturl.return_value = "https://example.com/catalog.json"++ entry = PresetCatalogEntry(+ url="https://example.com/catalog.json",+ name="default",+ priority=1,+ install_allowed=True,+ )++ with patch.object(catalog, "_open_url", return_value=mock_response), \+ patch.object(catalog, "get_active_catalogs", return_value=[entry]):+ merged = catalog._get_merged_packs(force_refresh=True)++ # Only the well-formed entry survives; the two malformed entries are+ # silently dropped rather than raising or crashing.+ assert list(merged.keys()) == ["good"]++ def test_download_pack_sends_auth_header(self, project_dir, monkeypatch):+ """download_pack passes Authorization header when configured."""+ from unittest.mock import patch, MagicMock++ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)++ import io+ zip_buf = io.BytesIO()+ with zipfile.ZipFile(zip_buf, "w") as zf:+ zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")+ zip_bytes = zip_buf.getvalue()++ release_response = MagicMock()+ release_response.read.side_effect = io.BytesIO(json.dumps(+ {+ "assets": [+ {+ "name": "test-pack.zip",+ "url": "https://api.github.com/repos/org/repo/releases/assets/1",+ }+ ]+ }+ ).encode()).read+ release_response.__enter__ = lambda s: s+ release_response.__exit__ = MagicMock(return_value=False)++ asset_response = MagicMock()+ asset_response.read.side_effect = io.BytesIO(zip_bytes).read+ asset_response.__enter__ = lambda s: s+ asset_response.__exit__ = MagicMock(return_value=False)++ captured = []+ mock_opener = MagicMock()++ def fake_open(req, timeout=None):+ captured.append(req)+ if req.full_url.endswith("/releases/tags/v1"):+ return release_response+ return asset_response++ mock_opener.open.side_effect = fake_open++ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://github.com/org/repo/releases/download/v1/test-pack.zip",+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):+ catalog.download_pack("test-pack", target_dir=project_dir)++ assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/tags/v1"+ assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"+ assert captured[1].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"+ assert captured[1].get_header("Authorization") == "Bearer ghp_testtoken"+ assert captured[1].get_header("Accept") == "application/octet-stream"++ def _pack_zip_and_response(self):+ """Build a minimal preset ZIP and a context-manager mock response."""+ from unittest.mock import MagicMock+ import io++ zip_buf = io.BytesIO()+ with zipfile.ZipFile(zip_buf, "w") as zf:+ zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")+ zip_bytes = zip_buf.getvalue()++ resp = MagicMock()+ resp.read.side_effect = io.BytesIO(zip_bytes).read+ # Configure the context-manager protocol explicitly so `with resp`+ # yields `resp` itself, independent of how the protocol is invoked.+ resp.__enter__.return_value = resp+ resp.__exit__.return_value = False+ return zip_bytes, resp++ def test_fetch_single_catalog_rejects_oversized_body_without_cache(+ self, project_dir, monkeypatch+ ):+ """Catalog bounds are enforced at the preset call site."""+ import specify_cli.presets as preset_module+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ entry = PresetCatalogEntry(+ url="https://example.com/catalog.json",+ name="default",+ priority=1,+ install_allowed=True,+ )+ body = b'{"schema_version":"1.0","presets":{}}'+ response = MagicMock()+ response.read.side_effect = io.BytesIO(body).read+ response.__enter__.return_value = response+ response.__exit__.return_value = False+ response.geturl.return_value = entry.url+ monkeypatch.setattr(+ preset_module,+ "MAX_JSON_CATALOG_BYTES",+ len(body) - 1,+ )++ with patch.object(catalog, "_open_url", return_value=response):+ with pytest.raises(PresetError, match="exceeds maximum size"):+ catalog._fetch_single_catalog(entry, force_refresh=True)++ assert not catalog.cache_dir.exists() or not any(catalog.cache_dir.iterdir())++ def test_download_pack_rejects_oversized_body_without_output(+ self, project_dir, monkeypatch+ ):+ """Package bounds fail before checksum verification or disk writes."""+ import specify_cli.presets as preset_module+ from unittest.mock import patch+ from specify_cli._download_security import (+ read_response_limited as real_read_response_limited,+ )++ catalog = PresetCatalog(project_dir)+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://example.com/test-pack.zip",+ "_install_allowed": True,+ }+ response = MagicMock()+ response.read.side_effect = io.BytesIO(b"12345").read+ response.__enter__.return_value = response+ response.__exit__.return_value = False++ def read_with_tiny_limit(stream, **kwargs):+ kwargs.pop("max_bytes", None)+ return real_read_response_limited(stream, max_bytes=4, **kwargs)++ monkeypatch.setattr(+ preset_module,+ "read_response_limited",+ read_with_tiny_limit,+ )+ with patch.object(preset_module, "verify_archive_sha256") as verify, \+ patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url", return_value=response):+ with pytest.raises(PresetError, match="exceeds maximum size"):+ catalog.download_pack("test-pack", target_dir=project_dir)++ verify.assert_not_called()+ assert not (project_dir / "test-pack-1.0.0.zip").exists()++ def test_download_pack_rejects_unsafe_output_filename(self, project_dir):+ """Catalog-controlled IDs cannot escape the requested target directory."""+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ outside_stem = project_dir.parent / "outside-preset"+ pack_id = str(outside_stem)+ pack_info = {+ "id": pack_id,+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://example.com/test-pack.zip",+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url") as open_url:+ with pytest.raises(PresetError, match="filename"):+ catalog.download_pack(pack_id, target_dir=project_dir)++ open_url.assert_not_called()+ assert not Path(f"{outside_stem}-1.0.0.zip").exists()++ def test_download_pack_accepts_matching_sha256(self, project_dir):+ """A catalog ``sha256`` that matches the preset archive is accepted."""+ import hashlib+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ zip_bytes, resp = self._pack_zip_and_response()+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://example.com/test-pack.zip",+ "sha256": hashlib.sha256(zip_bytes).hexdigest(),+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url", return_value=resp):+ zip_path = catalog.download_pack("test-pack", target_dir=project_dir)++ assert zip_path.read_bytes() == zip_bytes++ def test_download_pack_rejects_sha256_mismatch(self, project_dir):+ """A catalog ``sha256`` that does not match the archive aborts install."""+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ _zip_bytes, resp = self._pack_zip_and_response()+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://example.com/test-pack.zip",+ "sha256": "0" * 64, # deliberately wrong+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url", return_value=resp):+ with pytest.raises(PresetError, match="[Ii]ntegrity"):+ catalog.download_pack("test-pack", target_dir=project_dir)++ def test_download_pack_malformed_url_raises_preset_error(self, project_dir):+ """A catalog ``download_url`` with a malformed authority (e.g. an+ unterminated IPv6 bracket) surfaces a clean ``PresetError`` rather than+ leaking a raw ``ValueError`` from ``urlparse``/``.hostname`` past the+ command handler (which only catches ``PresetError``). Mirrors the+ extensions coverage.+ """+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ for bad_url in (+ "https://[::1",+ "https://[not-an-ip]/x",+ "https://example.com:65536/x",+ "https:///x",+ 123,+ ):+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": bad_url,+ "_install_allowed": True,+ }+ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url") as open_url:+ with pytest.raises(PresetError, match="malformed"):+ catalog.download_pack("test-pack", target_dir=project_dir)+ open_url.assert_not_called()++ def test_download_pack_without_sha256_skips_verification(self, project_dir):+ """A catalog entry with no ``sha256`` keeps working: verification is+ opt-in, so the backwards-compatible path (``pack_info.get("sha256")``+ is ``None``) must download without aborting β mirrors the extensions+ coverage so the helper never silently becomes mandatory for presets.+ """+ from unittest.mock import patch++ catalog = PresetCatalog(project_dir)+ zip_bytes, resp = self._pack_zip_and_response()+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://example.com/test-pack.zip",+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url", return_value=resp):+ zip_path = catalog.download_pack("test-pack", target_dir=project_dir)++ assert zip_path.read_bytes() == zip_bytes++ def test_download_pack_accepts_direct_github_rest_asset_url(self, project_dir, monkeypatch):+ """download_pack can use a GitHub REST release asset URL directly."""+ from unittest.mock import patch, MagicMock++ monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")+ self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")+ catalog = PresetCatalog(project_dir)++ import io+ zip_buf = io.BytesIO()+ with zipfile.ZipFile(zip_buf, "w") as zf:+ zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")+ zip_bytes = zip_buf.getvalue()++ asset_response = MagicMock()+ asset_response.read.side_effect = io.BytesIO(zip_bytes).read+ asset_response.__enter__ = lambda s: s+ asset_response.__exit__ = MagicMock(return_value=False)++ captured = []+ mock_opener = MagicMock()++ def fake_open(req, timeout=None):+ captured.append(req)+ return asset_response++ mock_opener.open.side_effect = fake_open++ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": "https://api.github.com/repos/org/repo/releases/assets/1",+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):+ catalog.download_pack("test-pack", target_dir=project_dir)++ assert len(captured) == 1+ assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"+ assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"+ assert captured[0].get_header("Accept") == "application/octet-stream"++ @pytest.mark.parametrize("suffix", [".tar.gz", ".tgz"])+ def test_download_pack_preserves_tar_archive_format(+ self, project_dir, suffix+ ):+ from unittest.mock import patch, MagicMock++ archive_buffer = io.BytesIO()+ with tarfile.open(fileobj=archive_buffer, mode="w:gz") as archive:+ content = b"preset:\n id: test-pack\n"+ member = tarfile.TarInfo("preset.yml")+ member.size = len(content)+ archive.addfile(member, io.BytesIO(content))+ archive_bytes = archive_buffer.getvalue()+ response = MagicMock()+ response.read.side_effect = io.BytesIO(archive_bytes).read+ response.__enter__.return_value = response+ response.__exit__.return_value = False+ catalog = PresetCatalog(project_dir)+ pack_info = {+ "id": "test-pack",+ "name": "Test Pack",+ "version": "1.0.0",+ "download_url": f"https://example.com/test-pack{suffix}",+ "_install_allowed": True,+ }++ with patch.object(catalog, "get_pack_info", return_value=pack_info), \+ patch.object(catalog, "_open_url", return_value=response):+ archive_path = catalog.download_pack("test-pack", target_dir=project_dir)++ assert archive_path.name == "test-pack-1.0.0.tar.gz"+ assert archive_path.read_bytes() == archive_bytes+++class TestPresetCatalogEntry:+ """Test PresetCatalogEntry dataclass."""++ def test_create_entry(self):+ """Test creating a catalog entry."""+ entry = PresetCatalogEntry(+ url="https://example.com/catalog.json",+ name="test",+ priority=1,+ install_allowed=True,+ description="Test catalog",+ )+ assert entry.url == "https://example.com/catalog.json"+ assert entry.name == "test"+ assert entry.priority == 1+ assert entry.install_allowed is True+ assert entry.description == "Test catalog"++ def test_default_description(self):+ """Test default empty description."""+ entry = PresetCatalogEntry(+ url="https://example.com/catalog.json",+ name="test",+ priority=1,+ install_allowed=False,+ )+ assert entry.description == ""+++class TestPresetCatalogMultiCatalog:+ """Test multi-catalog support in PresetCatalog."""++ def test_default_active_catalogs(self, project_dir):+ """Test that default catalogs are returned when no config exists."""+ catalog = PresetCatalog(project_dir)+ active = catalog.get_active_catalogs()+ assert len(active) == 2+ assert active[0].name == "default"+ assert active[0].priority == 1+ assert active[0].install_allowed is True+ assert active[1].name == "community"+ assert active[1].priority == 2+ assert active[1].install_allowed is False+++++++ def test_env_var_overrides_catalogs(self, project_dir, monkeypatch):+ """Test that SPECKIT_PRESET_CATALOG_URL env var overrides defaults."""+ monkeypatch.setenv(+ "SPECKIT_PRESET_CATALOG_URL",+ "https://custom.example.com/catalog.json",+ )+ catalog = PresetCatalog(project_dir)+ active = catalog.get_active_catalogs()+ assert len(active) == 1+ assert active[0].name == "custom"+ assert active[0].url == "https://custom.example.com/catalog.json"+ assert active[0].install_allowed is True++ def test_project_config_overrides_defaults(self, project_dir):+ """Test that project-level config overrides built-in defaults."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "my-catalog",+ "url": "https://my.example.com/catalog.json",+ "priority": 1,+ "install_allowed": True,+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ active = catalog.get_active_catalogs()+ assert len(active) == 1+ assert active[0].name == "my-catalog"+ assert active[0].url == "https://my.example.com/catalog.json"++ def test_load_catalog_config_nonexistent(self, project_dir):+ """Test loading config from nonexistent file returns None."""+ catalog = PresetCatalog(project_dir)+ result = catalog._load_catalog_config(+ project_dir / ".specify" / "nonexistent.yml"+ )+ assert result is None++ def test_load_catalog_config_empty(self, project_dir):+ """Test loading empty config returns None."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text("")++ catalog = PresetCatalog(project_dir)+ result = catalog._load_catalog_config(config_path)+ assert result is None++ def test_load_catalog_config_defaults_blank_names(self, project_dir):+ """Blank and null names normalize by valid catalog order."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(+ yaml.dump(+ {+ "catalogs": [+ {"name": "skipped", "url": " "},+ {+ "name": None,+ "url": "https://one.example.com/catalog.json",+ },+ {+ "name": " ",+ "url": "https://two.example.com/catalog.json",+ },+ {+ "name": " padded-name ",+ "url": "https://three.example.com/catalog.json",+ },+ ]+ }+ ),+ encoding="utf-8",+ )++ entries = PresetCatalog(project_dir)._load_catalog_config(config_path)++ assert [entry.name for entry in entries] == [+ "catalog-1",+ "catalog-2",+ "padded-name",+ ]++ @pytest.mark.parametrize("bad", [[], False, 0, ""])+ def test_load_catalog_config_rejects_falsy_non_mapping_root(+ self, project_dir, bad+ ):+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.safe_dump(bad), encoding="utf-8")++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="expected a mapping"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_invalid_yaml(self, project_dir):+ """Test loading invalid YAML raises error."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(": invalid: {{{")++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="Failed to read"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_not_a_list(self, project_dir):+ """Test that non-list catalogs key raises error."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({"catalogs": "not-a-list"}))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="must be a list"):+ catalog._load_catalog_config(config_path)++ @pytest.mark.parametrize("body", ["catalogs: {}\n", "catalogs: ''\n", "catalogs: 0\n", "catalogs: false\n"])+ def test_load_catalog_config_rejects_falsy_non_list_catalogs(self, project_dir, body):+ """A FALSY non-list ``catalogs:`` value must raise, like a truthy one+ (``catalogs: "not-a-list"``) already does. The shape check sat behind+ the emptiness check, so these were silently swallowed as "no catalogs"."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(body, encoding="utf-8")++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="must be a list"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_invalid_entry(self, project_dir):+ """Test that non-dict entry raises error."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({"catalogs": ["not-a-dict"]}))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="expected a mapping"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_http_url_rejected(self, project_dir):+ """Test that HTTP URLs are rejected."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "bad",+ "url": "http://insecure.example.com/catalog.json",+ "priority": 1,+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="must use HTTPS"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_priority_sorting(self, project_dir):+ """Test that catalogs are sorted by priority."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "low-priority",+ "url": "https://low.example.com/catalog.json",+ "priority": 10,+ "install_allowed": False,+ },+ {+ "name": "high-priority",+ "url": "https://high.example.com/catalog.json",+ "priority": 1,+ "install_allowed": True,+ },+ ]+ }))++ catalog = PresetCatalog(project_dir)+ entries = catalog._load_catalog_config(config_path)+ assert entries is not None+ assert len(entries) == 2+ assert entries[0].name == "high-priority"+ assert entries[1].name == "low-priority"++ def test_load_catalog_config_invalid_priority(self, project_dir):+ """Test that invalid priority raises error."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "bad",+ "url": "https://example.com/catalog.json",+ "priority": "not-a-number",+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid priority"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_rejects_boolean_priority(self, project_dir):+ """A YAML ``priority: true`` is a typo, not a request for priority 1.++ ``bool`` is a subclass of ``int`` in Python, so ``int(True)`` silently+ returns ``1``. Without an explicit guard a malformed config like+ ``priority: yes`` would be accepted as a valid priority of 1 and+ silently change catalog ordering. The sibling integration-catalog+ reader rejects this case (see ``catalogs.py``); the preset catalog+ reader must stay consistent.+ """+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "bool-priority",+ "url": "https://example.com/catalog.json",+ "priority": True,+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid priority|expected integer"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_rejects_infinite_priority(self, project_dir):+ """A ``priority: .inf`` yields a clean validation error, not an uncaught+ OverflowError from int(float('inf'))."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "inf-priority",+ "url": "https://example.com/catalog.json",+ "priority": float("inf"),+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid priority|expected integer"):+ catalog._load_catalog_config(config_path)++ def test_load_catalog_config_install_allowed_string(self, project_dir):+ """Test that install_allowed accepts string values."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "test",+ "url": "https://example.com/catalog.json",+ "priority": 1,+ "install_allowed": "true",+ }+ ]+ }))++ catalog = PresetCatalog(project_dir)+ entries = catalog._load_catalog_config(config_path)+ assert entries is not None+ assert entries[0].install_allowed is True++ def test_get_catalog_url_uses_highest_priority(self, project_dir):+ """Test that get_catalog_url returns URL of highest priority catalog."""+ config_path = project_dir / ".specify" / "preset-catalogs.yml"+ config_path.write_text(yaml.dump({+ "catalogs": [+ {+ "name": "secondary",+ "url": "https://secondary.example.com/catalog.json",+ "priority": 5,+ },+ {+ "name": "primary",+ "url": "https://primary.example.com/catalog.json",+ "priority": 1,+ },+ ]+ }))++ catalog = PresetCatalog(project_dir)+ assert catalog.get_catalog_url() == "https://primary.example.com/catalog.json"++ def test_cache_paths_default_url(self, project_dir):+ """Test cache paths for default catalog URL use legacy locations."""+ catalog = PresetCatalog(project_dir)+ cache_file, metadata_file = catalog._get_cache_paths(+ PresetCatalog.DEFAULT_CATALOG_URL+ )+ assert cache_file == catalog.cache_file+ assert metadata_file == catalog.cache_metadata_file++ def test_cache_paths_custom_url(self, project_dir):+ """Test cache paths for custom URLs use hash-based files."""+ catalog = PresetCatalog(project_dir)+ cache_file, metadata_file = catalog._get_cache_paths(+ "https://custom.example.com/catalog.json"+ )+ assert cache_file != catalog.cache_file+ assert "catalog-" in cache_file.name+ assert cache_file.name.endswith(".json")++ def test_url_cache_valid(self, project_dir):+ """Test URL-specific cache validation."""+ catalog = PresetCatalog(project_dir)+ url = "https://custom.example.com/catalog.json"+ cache_file, metadata_file = catalog._get_cache_paths(url)++ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))+ metadata_file.write_text(json.dumps({+ "cached_at": datetime.now(timezone.utc).isoformat(),+ }))++ assert catalog._is_url_cache_valid(url) is True++ def test_url_cache_expired(self, project_dir):+ """Test URL-specific cache expiration."""+ catalog = PresetCatalog(project_dir)+ url = "https://custom.example.com/catalog.json"+ cache_file, metadata_file = catalog._get_cache_paths(url)++ catalog.cache_dir.mkdir(parents=True, exist_ok=True)+ cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))+ metadata_file.write_text(json.dumps({+ "cached_at": "2020-01-01T00:00:00+00:00",+ }))++ assert catalog._is_url_cache_valid(url) is False+++class TestBundledPresetLocator:+ """Catalog downloads reject bundled presets."""++ def test_bundled_preset_download_raises_error(self, project_dir):+ """download_pack raises PresetError for bundled presets without download_url."""+ catalog = PresetCatalog(project_dir)++ catalog_data = {+ "test-bundled": {+ "name": "Test Bundled",+ "version": "1.0.0",+ "bundled": True,+ }+ }+ from unittest.mock import patch+ with patch.object(catalog, "_get_merged_packs", return_value=catalog_data):+ with pytest.raises(PresetError, match="bundled with spec-kit"):+ catalog.download_pack("test-bundled")+++def test_preset_wrapper_resolves_ghes_asset_when_host_configured(tmp_path, monkeypatch):+ """End-to-end wiring for presets: auth.json github host β GHES asset resolution."""+ from specify_cli.authentication import http as _auth_http+ from specify_cli.authentication.config import AuthConfigEntry+ from specify_cli.presets import PresetCatalog++ monkeypatch.setattr(_auth_http, "_config_override", [+ AuthConfigEntry(hosts=("ghes.example",), provider="github",+ auth="bearer", token="t"),+ ])+ catalog = PresetCatalog(tmp_path)++ captured = []++ @contextmanager+ def fake_open(url, timeout=None, extra_headers=None):+ captured.append(url)+ resp = MagicMock()+ resp.read.side_effect = io.BytesIO(json.dumps({+ "assets": [{"name": "pack.zip",+ "url": "https://ghes.example/api/v3/repos/o/r/releases/assets/9"}]+ }).encode()).read+ yield resp++ monkeypatch.setattr(catalog, "_open_url", fake_open)++ resolved = catalog._resolve_github_release_asset_api_url(+ "https://ghes.example/o/r/releases/download/v2/pack.zip"+ )+ assert resolved == "https://ghes.example/api/v3/repos/o/r/releases/assets/9"+ assert captured == ["https://ghes.example/api/v3/repos/o/r/releases/tags/v2"]diff --git a/tests/specify_cli/presets/test_domain_exports.py b/tests/specify_cli/presets/test_domain_exports.pynew file mode 100644index 000000000..b812b52f1--- /dev/null+++ b/tests/specify_cli/presets/test_domain_exports.py@@ -0,0 +1,30 @@+"""Existing preset import paths remain usable after the domain split."""++from importlib import import_module++import pytest++import specify_cli.presets as presets+++ ("name", "module"),+ [+ ("PresetError", "_manifest"),+ ("PresetValidationError", "_manifest"),+ ("PresetCompatibilityError", "_manifest"),+ ("PresetManifest", "_manifest"),+ ("PresetRegistry", "_registry"),+ ("PresetCatalogEntry", "_catalog"),+ ("PresetCatalog", "_catalog"),+ ("PresetResolver", "_resolver"),+ ("PresetManager", "_manager"),+ ("_materialize_constitution_template", "_manager"),+ ("_constitution_provenance_matches_preset", "_manager"),+ ("_substitute_core_template", "_manager_commands"),+ ],+)+def test_package_exports_preserve_private_implementation_identity(name, module):+ implementation = import_module(f"specify_cli.presets.{module}")++ assert getattr(presets, name) is getattr(implementation, name)diff --git a/tests/specify_cli/presets/test_manager.py b/tests/specify_cli/presets/test_manager.pynew file mode 100644index 000000000..91e080559--- /dev/null+++ b/tests/specify_cli/presets/test_manager.py@@ -0,0 +1,1609 @@+"""Tests for preset installation and removal in specify_cli.presets._manager."""++import json+import tarfile+import zipfile+from pathlib import Path++import pytest+import yaml++from specify_cli.presets import (+ PresetCompatibilityError,+ PresetError,+ PresetManager,+ PresetManifest,+ PresetResolver,+ PresetValidationError,+)+from tests.specify_cli.presets._helpers import (+ CORE_TEMPLATE_NAMES,+ PresetArtifactTestHelpers,+ install_constitution_sync_preset,+ install_self_test_preset,+)+from tests.specify_cli.presets._helpers import (+ make_convention_constitution_preset as _make_convention_constitution_preset,+)+++class TestPresetManifest:+ """Manager handling of invalid installed manifests."""++ def test_one_bad_manifest_does_not_hide_healthy_presets(self, temp_dir):+ """End-to-end guard for the symptom: an unquoted ``version: 1.0`` in one+ installed preset must degrade to "Corrupted preset" and still let+ list_installed() report the healthy ones, instead of raising TypeError+ out of the whole call.+ """+ preset_root = temp_dir / ".specify" / "presets"+ for pack_id, version in (("good-pack", '"1.0.0"'), ("bad-pack", "1.0")):+ pack_path = preset_root / pack_id+ pack_path.mkdir(parents=True, exist_ok=True)+ (pack_path / "preset.yml").write_text(+ f"""schema_version: "1.0"+preset:+ id: {pack_id}+ name: {pack_id}+ version: {version}+ description: desc+requires:+ speckit_version: ">=0.1.0"+provides:+ templates:+ - type: template+ name: spec+ file: templates/spec.md+""",+ encoding="utf-8",+ )+ (preset_root / ".registry").write_text(+ json.dumps(+ {+ "schema_version": "1.0",+ "presets": {+ "good-pack": {"version": "1.0.0", "enabled": True},+ "bad-pack": {"version": "1.0", "enabled": True},+ },+ }+ ),+ encoding="utf-8",+ )++ listed = {row["id"]: row for row in PresetManager(temp_dir).list_installed()}++ assert set(listed) == {"good-pack", "bad-pack"}+ assert "Corrupted" not in listed["good-pack"]["description"]+ assert "Corrupted" in listed["bad-pack"]["description"]+++def test_unreadable_constitution_provenance_fails_closed(+ project_dir, monkeypatch+):+ from specify_cli.presets import _constitution_provenance_matches_preset++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ memory.write_text("# Constitution\n", encoding="utf-8")+ provenance = memory.parent / ".constitution-template.json"+ provenance.write_text("{}", encoding="utf-8")+ real_read_text = Path.read_text++ def unreadable(path, *args, **kwargs):+ if path == provenance:+ raise OSError("simulated read failure")+ return real_read_text(path, *args, **kwargs)++ monkeypatch.setattr(Path, "read_text", unreadable)++ assert not _constitution_provenance_matches_preset(+ project_dir, memory, "example", "1.0.0"+ )+++class TestPresetManager:+ """Test PresetManager installation and removal."""++ def test_install_from_directory(self, project_dir, pack_dir):+ """Test installing a preset from a directory."""+ manager = PresetManager(project_dir)+ manifest = manager.install_from_directory(pack_dir, "0.1.5")++ assert manifest.id == "test-pack"+ assert manager.registry.is_installed("test-pack")++ # Verify files are copied+ installed_dir = project_dir / ".specify" / "presets" / "test-pack"+ assert installed_dir.exists()+ assert (installed_dir / "preset.yml").exists()+ assert (installed_dir / "templates" / "spec-template.md").exists()++ def test_install_already_installed(self, project_dir, pack_dir):+ """Test installing an already-installed pack raises error."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ with pytest.raises(PresetError, match="already installed"):+ manager.install_from_directory(pack_dir, "0.1.5")++ def test_install_incompatible(self, project_dir, temp_dir, valid_pack_data):+ """Test installing an incompatible pack raises error."""+ valid_pack_data["requires"]["speckit_version"] = ">=99.0.0"+ incompat_dir = temp_dir / "incompat-pack"+ incompat_dir.mkdir()+ manifest_path = incompat_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (incompat_dir / "templates").mkdir()+ (incompat_dir / "templates" / "spec-template.md").write_text("test")++ manager = PresetManager(project_dir)+ with pytest.raises(PresetCompatibilityError):+ manager.install_from_directory(incompat_dir, "0.1.5")++ def test_install_from_zip(self, project_dir, pack_dir, temp_dir):+ """Test installing from a ZIP file."""+ zip_path = temp_dir / "test-pack.zip"+ with zipfile.ZipFile(zip_path, 'w') as zf:+ for file_path in pack_dir.rglob('*'):+ if file_path.is_file():+ arcname = file_path.relative_to(pack_dir)+ zf.write(file_path, arcname)++ manager = PresetManager(project_dir)+ manifest = manager.install_from_zip(+ zip_path, "0.1.5", catalog_name="preset-catalog"+ )+ assert manifest.id == "test-pack"+ assert manager.registry.is_installed("test-pack")+ assert manager.registry.get("test-pack")["source"] == {+ "kind": "catalog",+ "catalog": "preset-catalog",+ }++ def test_install_from_zip_forwards_force(+ self, project_dir, pack_dir, temp_dir+ ):+ """The compatibility wrapper must retain forced reinstall behavior."""+ zip_path = temp_dir / "test-pack.zip"+ with zipfile.ZipFile(zip_path, "w") as zf:+ for file_path in pack_dir.rglob("*"):+ if file_path.is_file():+ zf.write(file_path, file_path.relative_to(pack_dir))++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")+ manifest = manager.install_from_zip(+ zip_path,+ "0.1.5",+ force=True,+ )++ assert manifest.id == "test-pack"+ assert manager.registry.is_installed("test-pack")++ def test_install_from_zip_nested(self, project_dir, pack_dir, temp_dir):+ """Test installing from ZIP with nested directory."""+ zip_path = temp_dir / "test-pack.zip"+ with zipfile.ZipFile(zip_path, 'w') as zf:+ for file_path in pack_dir.rglob('*'):+ if file_path.is_file():+ arcname = Path("test-pack-v1.0.0") / file_path.relative_to(pack_dir)+ zf.write(file_path, arcname)++ manager = PresetManager(project_dir)+ manifest = manager.install_from_zip(zip_path, "0.1.5")+ assert manifest.id == "test-pack"++ def test_install_from_zip_no_manifest(self, project_dir, temp_dir):+ """Test installing from ZIP without manifest raises error."""+ zip_path = temp_dir / "bad.zip"+ with zipfile.ZipFile(zip_path, 'w') as zf:+ zf.writestr("readme.txt", "no manifest here")++ manager = PresetManager(project_dir)+ with pytest.raises(PresetValidationError, match="No preset.yml found"):+ manager.install_from_zip(zip_path, "0.1.5")++ def test_install_from_zip_rejects_symlink_entry(+ self, project_dir, pack_dir, temp_dir+ ):+ """Preset ZIPs delegate to the shared symlink-safe extractor."""+ import stat++ zip_path = temp_dir / "symlink-preset.zip"+ link = zipfile.ZipInfo("templates/escape")+ link.create_system = 3+ link.external_attr = (stat.S_IFLNK | 0o777) << 16+ with zipfile.ZipFile(zip_path, "w") as zf:+ for file_path in pack_dir.rglob("*"):+ if file_path.is_file():+ zf.write(file_path, file_path.relative_to(pack_dir))+ zf.writestr(link, "../../outside")++ manager = PresetManager(project_dir)+ with pytest.raises(PresetValidationError, match="Unsafe symlink"):+ manager.install_from_zip(zip_path, "0.1.5")++ assert not manager.registry.is_installed("test-pack")++ @pytest.mark.parametrize("suffix", [".tar.gz", ".tgz"])+ @pytest.mark.parametrize("nested", [False, True])+ def test_install_from_tar_archive(+ self, project_dir, pack_dir, temp_dir, suffix, nested+ ):+ """Tar archives install with the same flat/nested behavior as ZIP."""+ archive_path = temp_dir / f"test-pack{suffix}"+ with tarfile.open(archive_path, "w:gz") as archive:+ for file_path in pack_dir.rglob("*"):+ if file_path.is_file():+ relative = file_path.relative_to(pack_dir)+ arcname = Path("test-pack-v1") / relative if nested else relative+ archive.add(file_path, arcname=arcname)++ manager = PresetManager(project_dir)+ manifest = manager.install_from_archive(+ archive_path, "0.1.5", catalog_name="preset-catalog"+ )++ assert manifest.id == "test-pack"+ assert manager.registry.is_installed("test-pack")+ assert manager.registry.get("test-pack")["source"] == {+ "kind": "catalog",+ "catalog": "preset-catalog",+ }++ def test_install_from_tar_rejects_symlink_entry(+ self, project_dir, pack_dir, temp_dir+ ):+ archive_path = temp_dir / "symlink-preset.tar.gz"+ with tarfile.open(archive_path, "w:gz") as archive:+ for file_path in pack_dir.rglob("*"):+ if file_path.is_file():+ archive.add(file_path, arcname=file_path.relative_to(pack_dir))+ link = tarfile.TarInfo("templates/escape")+ link.type = tarfile.SYMTYPE+ link.linkname = "../../outside"+ archive.addfile(link)++ manager = PresetManager(project_dir)+ with pytest.raises(PresetValidationError, match="Unsafe symlink"):+ manager.install_from_archive(archive_path, "0.1.5")++ assert not manager.registry.is_installed("test-pack")++ def test_remove(self, project_dir, pack_dir):+ """Test removing a preset."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")+ assert manager.registry.is_installed("test-pack")++ result = manager.remove("test-pack")+ assert result is True+ assert not manager.registry.is_installed("test-pack")++ installed_dir = project_dir / ".specify" / "presets" / "test-pack"+ assert not installed_dir.exists()++ def test_remove_nonexistent(self, project_dir):+ """Test removing a pack that doesn't exist."""+ manager = PresetManager(project_dir)+ result = manager.remove("nonexistent")+ assert result is False++ def test_list_installed(self, project_dir, pack_dir):+ """Test listing installed packs."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ installed = manager.list_installed()+ assert len(installed) == 1+ assert installed[0]["id"] == "test-pack"+ assert installed[0]["name"] == "Test Preset"+ assert installed[0]["version"] == "1.0.0"+ assert installed[0]["template_count"] == 1++ def test_list_installed_empty(self, project_dir):+ """Test listing when no packs installed."""+ manager = PresetManager(project_dir)+ assert manager.list_installed() == []++ def test_get_pack(self, project_dir, pack_dir):+ """Test getting a specific installed pack."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ pack = manager.get_pack("test-pack")+ assert pack is not None+ assert pack.id == "test-pack"++ def test_get_pack_not_installed(self, project_dir):+ """Test getting a non-installed pack returns None."""+ manager = PresetManager(project_dir)+ assert manager.get_pack("nonexistent") is None++ def test_check_compatibility_valid(self, pack_dir, temp_dir):+ """Test compatibility check with valid version."""+ manager = PresetManager(temp_dir)+ manifest = PresetManifest(pack_dir / "preset.yml")+ assert manager.check_compatibility(manifest, "0.1.5") is True++ def test_check_compatibility_prerelease(self, pack_dir, temp_dir):+ """Test compatibility check allows prereleases and fails on boundary."""+ manager = PresetManager(temp_dir)+ manifest = PresetManifest(pack_dir / "preset.yml")+ # manifest requires >=0.1.0+ assert manager.check_compatibility(manifest, "0.8.8.dev0") is True+ with pytest.raises(PresetCompatibilityError, match="Preset requires spec-kit"):+ manager.check_compatibility(manifest, "0.1.0.dev0")++ def test_check_compatibility_invalid(self, pack_dir, temp_dir):+ """Test compatibility check with invalid specifier."""+ manager = PresetManager(temp_dir)+ manifest = PresetManifest(pack_dir / "preset.yml")+ manifest.data["requires"]["speckit_version"] = "not-a-specifier"+ with pytest.raises(PresetCompatibilityError, match="Invalid version specifier"):+ manager.check_compatibility(manifest, "0.1.5")++ @pytest.mark.parametrize(+ "bad",+ [1.0, 5, True, None, [">=0.1.0"], {"min": "0.1"}],+ )+ def test_check_compatibility_non_string_specifier(self, pack_dir, temp_dir, bad):+ """check_compatibility() must report a non-string as a compatibility error.++ Defense in depth for the validator check: this method is public and the+ specifier is read back out of mutable manifest data, and ``except+ InvalidSpecifier`` does not cover a non-string. Without the guard, scalars+ raise a bare TypeError and iterables construct fine only to break inside+ .contains() -- neither is a PresetCompatibilityError, so both bypass the+ CLI's "Compatibility Error" handler and exit 1 with a raw traceback.+ """+ manager = PresetManager(temp_dir)+ manifest = PresetManifest(pack_dir / "preset.yml")+ manifest.data["requires"]["speckit_version"] = bad+ with pytest.raises(PresetCompatibilityError, match="Invalid version specifier"):+ manager.check_compatibility(manifest, "0.1.5")++ def test_install_with_priority(self, project_dir, pack_dir):+ """Test installing a pack with custom priority."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5", priority=5)++ metadata = manager.registry.get("test-pack")+ assert metadata is not None+ assert metadata["priority"] == 5++ def test_install_default_priority(self, project_dir, pack_dir):+ """Test that default priority is 10."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ metadata = manager.registry.get("test-pack")+ assert metadata is not None+ assert metadata["priority"] == 10++ def test_list_installed_includes_priority(self, project_dir, pack_dir):+ """Test that list_installed includes priority."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5", priority=3)++ installed = manager.list_installed()+ assert len(installed) == 1+ assert installed[0]["priority"] == 3+++class TestPresetExtensionDependencies:+ """Test find_unmet_extension_dependencies (issue #4231)."""++ @staticmethod+ def _install_extension(+ project_dir, extension_id, version, enabled=True, with_files=True+ ):+ """Register an installed extension the way the extension installer does.++ ``with_files=False`` leaves the registry entry without its directory,+ reproducing the stale state left behind when the files are deleted out+ from under the registry.+ """+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True, exist_ok=True)+ if with_files:+ (extensions_dir / extension_id).mkdir(parents=True, exist_ok=True)+ registry_path = extensions_dir / ".registry"+ data = {"schema_version": "1.0", "extensions": {}}+ if registry_path.exists():+ data = json.loads(registry_path.read_text(encoding="utf-8"))+ data["extensions"][extension_id] = {"version": version, "enabled": enabled}+ registry_path.write_text(json.dumps(data), encoding="utf-8")++ @staticmethod+ def _manifest(temp_dir, valid_pack_data, declared):+ valid_pack_data["requires"]["extensions"] = declared+ manifest_path = temp_dir / "dep-preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ return PresetManifest(manifest_path)++ def test_no_declared_dependencies_is_satisfied(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A preset declaring nothing never reports an unmet dependency."""+ manifest_path = temp_dir / "plain-preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)++ manager = PresetManager(project_dir)+ assert manager.find_unmet_extension_dependencies(+ PresetManifest(manifest_path)+ ) == []++ def test_missing_dependency_is_reported(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """An uninstalled required extension is reported as missing."""+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert len(unmet) == 1+ assert unmet[0]["id"] == "speckit-inventory"+ assert unmet[0]["reason"] == "missing"+ assert unmet[0]["installed"] is None++ def test_installed_dependency_is_satisfied(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """An installed extension with no version constraint is satisfied."""+ self._install_extension(project_dir, "speckit-inventory", "0.1.0")+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ def test_satisfied_version_constraint(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A satisfied version constraint reports nothing."""+ self._install_extension(project_dir, "speckit-inventory", "1.5.0")+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=1.2.0"}],+ )++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ def test_unsatisfied_version_constraint_reports_both_versions(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A version mismatch reports the installed version alongside the constraint."""+ self._install_extension(project_dir, "speckit-inventory", "0.1.0")+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=9.0.0"}],+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert len(unmet) == 1+ assert unmet[0]["reason"] == "version"+ assert unmet[0]["installed"] == "0.1.0"+ assert unmet[0]["version"] == ">=9.0.0"+++ def test_optional_dependency_is_never_reported(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """`required: false` opts out of the warning even when absent."""+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "required": False}],+ )++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ @pytest.mark.parametrize("bad_version", [None, 5, "unknown", "", "latest"])+ def test_uncomparable_registry_version_is_not_a_mismatch(+ self, project_dir, temp_dir, valid_pack_data, bad_version+ ):+ """A version that cannot be evaluated must not be reported as a mismatch.++ ``version_satisfies()`` returns False for an unparseable version, which+ is indistinguishable from a genuine mismatch -- so a string like+ "unknown" would otherwise be reported as failing a constraint nobody+ can actually evaluate it against.+ """+ self._install_extension(project_dir, "speckit-inventory", "0.1.0")+ registry_path = project_dir / ".specify" / "extensions" / ".registry"+ data = json.loads(registry_path.read_text(encoding="utf-8"))+ data["extensions"]["speckit-inventory"]["version"] = bad_version+ registry_path.write_text(json.dumps(data), encoding="utf-8")++ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=9.0.0"}],+ )++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ def test_unregistered_extension_on_disk_is_satisfied(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A directory with no registry entry still resolves, so it is not missing.++ ``_get_all_extensions_by_priority`` admits safe unregistered+ directories at implicit priority 10, so the preset works -- warning+ that the dependency is absent would be a false alarm.+ """+ (project_dir / ".specify" / "extensions" / "speckit-inventory").mkdir(+ parents=True+ )+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ def test_unregistered_extension_cannot_be_version_checked(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """No registry entry means no recorded version, so nothing to compare."""+ (project_dir / ".specify" / "extensions" / "speckit-inventory").mkdir(+ parents=True+ )+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=9.0.0"}],+ )++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++ def test_corrupted_registry_entry_with_directory_is_not_satisfied(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A corrupted entry keeps its id registered, so its directory is excluded.++ ``get()`` returns None for a non-dict entry just as it does for an+ absent one, but ``keys()`` retains the id specifically so resolution+ does not re-admit the directory as an unregistered extension. The+ fallback must not revive what resolution excludes.+ """+ extensions_dir = project_dir / ".specify" / "extensions"+ (extensions_dir / "speckit-inventory").mkdir(parents=True)+ (extensions_dir / ".registry").write_text(+ json.dumps(+ {"schema_version": "1.0", "extensions": {"speckit-inventory": "corrupt"}}+ ),+ encoding="utf-8",+ )+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ # Reported as corrupt rather than missing: the id is still registered,+ # so a plain `extension add` would be refused as already installed.+ assert [dep["reason"] for dep in unmet] == ["corrupt"]+++++ def test_unregistered_extension_with_corrupt_registry_is_missing(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A corrupt registry makes resolution fail closed, so it is not usable."""+ extensions_dir = project_dir / ".specify" / "extensions"+ (extensions_dir / "speckit-inventory").mkdir(parents=True)+ (extensions_dir / ".registry").write_text("{not valid json", encoding="utf-8")+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["reason"] for dep in unmet] == ["missing"]++ def test_corrupted_entry_gets_a_forced_reinstall_remedy(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A corrupted entry is not simply absent: `add <id>` would be refused.++ ``get()`` returns None for it, but ``is_installed()`` still counts the+ key, so a plain add reports "already installed". It needs --force.+ """+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True)+ (extensions_dir / ".registry").write_text(+ json.dumps(+ {"schema_version": "1.0", "extensions": {"speckit-inventory": "bad"}}+ ),+ encoding="utf-8",+ )+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["reason"] for dep in unmet] == ["corrupt"]+++ def test_unreadable_registry_does_not_raise(+ self, project_dir, temp_dir, valid_pack_data, monkeypatch+ ):+ """An OSError from the registry must not crash an already-completed install.++ ``_load()`` lets OSError through, and ``preset_add`` only handles+ preset-domain errors, so raising here would turn a finished install+ into a traceback over what is only a warning.+ """+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ import specify_cli.presets as presets_mod++ def _boom(*args, **kwargs):+ raise PermissionError("registry unreadable")++ monkeypatch.setattr(presets_mod, "ExtensionRegistry", _boom)++ assert PresetManager(project_dir).find_unmet_extension_dependencies(+ manifest+ ) == []++++ def test_exact_duplicate_declarations_warn_once(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """Naming the same dependency twice must not print the warning twice."""+ manifest = self._manifest(+ temp_dir, valid_pack_data, ["speckit-inventory", "speckit-inventory"]+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["id"] for dep in unmet] == ["speckit-inventory"]++ def test_same_id_with_different_constraints_is_checked_twice(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """Distinct constraints on one id both have to hold, so both are checked."""+ self._install_extension(project_dir, "speckit-inventory", "1.0.0")+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [+ {"id": "speckit-inventory", "version": ">=9.0.0"},+ {"id": "speckit-inventory", "version": "<0.5"},+ ],+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["version"] for dep in unmet] == [">=9.0.0", "<0.5"]++ def test_stale_registry_entry_is_reported(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A registry entry whose extension directory is gone counts as unmet.++ PresetResolver guards on ``ext_dir.is_dir()`` in both template lookup+ and layer collection, so a stale entry contributes nothing -- but the+ surviving registry entry would otherwise read as satisfied.+ """+ self._install_extension(+ project_dir, "speckit-inventory", "0.1.0", with_files=False+ )+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert len(unmet) == 1+ assert unmet[0]["reason"] == "stale"+ assert unmet[0]["installed"] == "0.1.0"++ def test_stale_is_reported_ahead_of_disabled_and_version(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """Restoring the files is the prerequisite, so it is reported first."""+ self._install_extension(+ project_dir, "speckit-inventory", "0.1.0",+ enabled=False, with_files=False,+ )+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=9.0.0"}],+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["reason"] for dep in unmet] == ["stale"]+++ def test_disabled_dependency_is_reported(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """A disabled extension contributes nothing, so it counts as unmet.++ Resolution skips disabled extensions, leaving the preset just as inert+ as if the extension were absent -- but the registry entry exists, so a+ presence-only check would call it satisfied and stay silent.+ """+ self._install_extension(project_dir, "speckit-inventory", "0.1.0", enabled=False)+ manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert len(unmet) == 1+ assert unmet[0]["reason"] == "disabled"+ assert unmet[0]["installed"] == "0.1.0"++ def test_disabled_is_reported_ahead_of_version_mismatch(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """Enabling is the prerequisite, so it is reported before the version."""+ self._install_extension(project_dir, "speckit-inventory", "0.1.0", enabled=False)+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [{"id": "speckit-inventory", "version": ">=9.0.0"}],+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [dep["reason"] for dep in unmet] == ["disabled"]++ def test_multiple_dependencies_report_independently(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """Each declared dependency is evaluated on its own."""+ self._install_extension(project_dir, "present-ext", "1.0.0")+ self._install_extension(project_dir, "off-ext", "1.0.0", enabled=False)+ manifest = self._manifest(+ temp_dir, valid_pack_data,+ [+ "present-ext",+ "absent-ext",+ "off-ext",+ {"id": "opt-ext", "required": False},+ ],+ )++ unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)++ assert [(dep["id"], dep["reason"]) for dep in unmet] == [+ ("absent-ext", "missing"),+ ("off-ext", "disabled"),+ ]+++class TestSelfTestPreset:+ """Installation, removal, and constitution materialization using self-test."""++ def test_install_self_test_preset(self, project_dir):+ """Test installing the self-test preset from its directory."""+ manager = PresetManager(project_dir)+ manifest = install_self_test_preset(manager)+ assert manifest.id == "self-test"+ assert manager.registry.is_installed("self-test")++ def test_self_test_removal_restores_core(self, project_dir):+ """Test that removing self-test falls back to core templates."""+ templates_dir = project_dir / ".specify" / "templates"+ for name in CORE_TEMPLATE_NAMES:+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)+ manager.remove("self-test")++ resolver = PresetResolver(project_dir)+ for name in CORE_TEMPLATE_NAMES:+ result = resolver.resolve_with_source(name)+ assert result is not None+ assert result["source"] == "core"++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert memory.read_text() == "# Core constitution-template\n"++ def test_self_test_removal_preserves_edited_constitution(self, project_dir):+ """Removing a preset does not overwrite an edited generated constitution."""+ templates_dir = project_dir / ".specify" / "templates"+ (templates_dir / "constitution-template.md").write_text("# Core Constitution\n")++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ edited = memory.read_text() + "\n## Authored amendment\n"+ memory.write_text(edited)++ manager.remove("self-test")++ assert memory.read_text() == edited++ def test_self_test_does_not_seed_constitution_without_sync(self, project_dir):+ """Installing a preset does not materialize its constitution by default."""+ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert not memory.exists()++ def test_self_test_preserves_generated_constitution_without_sync(self, project_dir):+ """Preset install and removal preserve generated content without the opt-in."""+ resolver = PresetResolver(project_dir)+ bundled_core = resolver._find_bundled_core(+ "constitution-template", "template", ".md"+ )+ assert bundled_core is not None+ core = bundled_core.read_bytes()+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ memory.write_bytes(core)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)+ manager.remove("self-test")++ assert memory.read_bytes() == core++ def test_self_test_seeds_constitution_with_sync(self, project_dir):+ """constitution-sync preserves the previous install-time seeding behavior."""+ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert "preset:self-test" in memory.read_text()+ assert "[PROJECT_NAME]" not in memory.read_text()++ @pytest.mark.parametrize(+ "provenance_content",+ [+ '{"sha256": "does-not-match", "source": "old-preset"}\n',+ "{not valid json",+ ],+ ids=["hash-mismatch", "malformed"],+ )+ def test_self_test_preserves_core_content_with_existing_invalid_provenance(+ self, project_dir, provenance_content+ ):+ """A present invalid sidecar disables legacy core-template migration."""+ resolver = PresetResolver(project_dir)+ bundled_core = resolver._find_bundled_core(+ "constitution-template", "template", ".md"+ )+ assert bundled_core is not None+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ memory.write_bytes(bundled_core.read_bytes())+ (memory.parent / ".constitution-template.json").write_text(+ provenance_content+ )+ original = memory.read_bytes()++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ assert memory.read_bytes() == original++ def test_self_test_preserves_mutable_project_core_copy(self, project_dir):+ """A project template copy does not establish generated provenance."""+ authored = "# Acme Organization Constitution\n\nOrganization policy.\n"+ project_template = (+ project_dir / ".specify" / "templates" / "constitution-template.md"+ )+ project_template.write_text(authored)+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ memory.write_text(authored)++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ assert memory.read_text() == authored+ assert not (memory.parent / ".constitution-template.json").exists()++ def test_core_prefixed_preset_does_not_establish_generated_provenance(+ self, project_dir, temp_dir+ ):+ """A preset ID beginning with core is not an immutable core source."""+ authored = "# Acme Organization Constitution\n\nOrganization policy.\n"+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ memory.write_text(authored)++ preset_dir = temp_dir / "core-company"+ (preset_dir / "templates").mkdir(parents=True)+ (preset_dir / "templates" / "constitution-template.md").write_text(authored)+ (preset_dir / "preset.yml").write_text(+ yaml.safe_dump(+ {+ "schema_version": "1.0",+ "preset": {+ "id": "core-company",+ "name": "Core Company",+ "version": "1.0.0",+ "description": "Company constitution preset",+ "author": "Test Author",+ "repository": "https://github.com/test/core-company",+ "license": "MIT",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "constitution-template",+ "file": "templates/constitution-template.md",+ "description": "Company constitution",+ "replaces": "constitution-template",+ }+ ]+ },+ }+ )+ )++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ manager.install_from_directory(preset_dir, "0.1.5")++ assert memory.read_text() == authored+ assert not (memory.parent / ".constitution-template.json").exists()++ def test_self_test_preserves_authored_constitution_with_placeholder(+ self, project_dir+ ):+ """A placeholder mention does not establish generated provenance."""+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ authored = "# Acme Constitution\n\nGuidance for [PROJECT_NAME].\n"+ memory.write_text(authored)++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ assert memory.read_text() == authored++ def test_self_test_preserves_authored_constitution(self, project_dir):+ """An authored (placeholder-free) constitution is never overwritten."""+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ memory.parent.mkdir(parents=True, exist_ok=True)+ authored = "# Acme Constitution\n\n### I. Ship It\nAuthored by a human.\n"+ memory.write_text(authored)++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ assert memory.read_text() == authored, "authored constitution was overwritten"++ def test_constitution_seed_composes_wrap_strategy(self, project_dir, temp_dir):+ """Seeding memory composes wrap constitution-template layers."""+ templates_dir = project_dir / ".specify" / "templates"+ templates_dir.mkdir(parents=True, exist_ok=True)+ (templates_dir / "constitution-template.md").write_text(+ "# Core Constitution\n\n## Core Principle\n"+ )++ preset_dir = temp_dir / "constitution-wrap"+ (preset_dir / "templates").mkdir(parents=True)+ (preset_dir / "templates" / "constitution-template.md").write_text(+ "# Wrapper Constitution\n\n{CORE_TEMPLATE}\n\n## Wrapper Footer\n"+ )+ (preset_dir / "preset.yml").write_text(+ yaml.dump(+ {+ "schema_version": "1.0",+ "preset": {+ "id": "constitution-wrap",+ "name": "Constitution Wrap",+ "version": "1.0.0",+ "description": "Wrap constitution template for testing",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "constitution-template",+ "file": "templates/constitution-template.md",+ "strategy": "wrap",+ "description": "Wrapped constitution template",+ }+ ]+ },+ }+ )+ )++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ manager.install_from_directory(preset_dir, "0.1.5")++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ content = memory.read_text()+ assert "{CORE_TEMPLATE}" not in content+ assert "# Wrapper Constitution" in content+ assert "## Core Principle" in content++ def test_constitution_follows_priority_when_winning_preset_removed(+ self, project_dir, temp_dir+ ):+ """An unchanged generated constitution follows priority and fallback layers."""+ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ preset_dir = temp_dir / "higher-priority"+ (preset_dir / "templates").mkdir(parents=True)+ (preset_dir / "templates" / "constitution-template.md").write_text(+ "# Higher Priority Constitution\n"+ )+ (preset_dir / "preset.yml").write_text(+ yaml.dump(+ {+ "schema_version": "1.0",+ "preset": {+ "id": "higher-priority",+ "name": "Higher Priority",+ "version": "1.0.0",+ "description": "Higher-priority constitution",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "constitution-template",+ "file": "templates/constitution-template.md",+ "strategy": "replace",+ "description": "Higher-priority constitution",+ }+ ]+ },+ }+ )+ )++ manager.install_from_directory(preset_dir, "0.1.5", priority=1)++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert memory.read_text() == "# Higher Priority Constitution\n"++ manager.remove("higher-priority")++ assert "preset:self-test" in memory.read_text()++ def test_convention_constitution_removal_restores_remaining_layer(+ self, project_dir, temp_dir+ ):+ """Removing a convention layer rematerializes the remaining resolver layer."""+ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)+ manager.install_from_directory(+ _make_convention_constitution_preset(temp_dir), "0.1.5", priority=1+ )++ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert memory.read_text() == "# Convention Constitution\n"++ manager.remove("convention-constitution")++ assert "preset:self-test" in memory.read_text()++ def test_convention_constitution_removal_preserves_edited_content(+ self, project_dir, temp_dir+ ):+ """Removing a convention layer does not overwrite edited generated content."""+ from specify_cli.command_init import ensure_constitution_from_template++ templates_dir = project_dir / ".specify" / "templates"+ (templates_dir / "constitution-template.md").write_text("# Core Constitution\n")+ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ manager.install_from_directory(+ _make_convention_constitution_preset(temp_dir), "0.1.5"+ )+ ensure_constitution_from_template(project_dir)+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ edited = memory.read_text() + "\n## Authored amendment\n"+ memory.write_text(edited)++ manager.remove("convention-constitution")++ assert memory.read_text() == edited++ def test_custom_constitution_removal_recovers_with_invalid_manifest(+ self, project_dir, temp_dir+ ):+ """Provenance triggers fallback when a custom-path manifest is invalid."""+ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ install_self_test_preset(manager)++ preset_dir = temp_dir / "custom-constitution"+ (preset_dir / "policy").mkdir(parents=True)+ (preset_dir / "policy" / "charter.md").write_text("# Custom Constitution\n")+ (preset_dir / "preset.yml").write_text(+ yaml.dump(+ {+ "schema_version": "1.0",+ "preset": {+ "id": "custom-constitution",+ "name": "Custom Constitution",+ "version": "1.0.0",+ "description": "Custom-path constitution for testing",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "constitution-template",+ "file": "policy/charter.md",+ }+ ]+ },+ }+ )+ )+ manager.install_from_directory(preset_dir, "0.1.5", priority=1)+ memory = project_dir / ".specify" / "memory" / "constitution.md"+ assert memory.read_text() == "# Custom Constitution\n"++ installed_manifest = (+ project_dir+ / ".specify"+ / "presets"+ / "custom-constitution"+ / "preset.yml"+ )+ installed_manifest.write_text("invalid: [")++ manager.remove("custom-constitution")++ assert "preset:self-test" in memory.read_text()++ def test_constitution_seed_rejects_symlinked_memory_directory(+ self, project_dir, temp_dir+ ):+ """Preset installation cannot seed through a symlinked memory directory."""+ outside = temp_dir / "outside"+ outside.mkdir()+ try:+ (project_dir / ".specify" / "memory").symlink_to(+ outside, target_is_directory=True+ )+ except OSError:+ pytest.skip("symlinks are unavailable")++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="symlinked"):+ install_constitution_sync_preset(manager)++ assert manager.registry.is_installed("constitution-sync")+ assert not (outside / "constitution.md").exists()++ def test_constitution_seed_rejects_dangling_destination_symlink(+ self, project_dir, temp_dir+ ):+ """Preset installation cannot seed through a dangling destination symlink."""+ memory = project_dir / ".specify" / "memory"+ memory.mkdir(parents=True)+ outside = temp_dir / "outside-constitution.md"+ try:+ (memory / "constitution.md").symlink_to(outside)+ except OSError:+ pytest.skip("symlinks are unavailable")++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="symlinked"):+ install_constitution_sync_preset(manager)++ assert manager.registry.is_installed("constitution-sync")+ assert not outside.exists()++ def test_constitution_materialization_error_is_nonfatal(+ self, project_dir, temp_dir+ ):+ """An invalid wrap warns without reporting an uninstalled preset."""+ preset_dir = temp_dir / "invalid-wrap"+ (preset_dir / "templates").mkdir(parents=True)+ (preset_dir / "templates" / "constitution-template.md").write_text(+ "# Missing core placeholder\n"+ )+ (preset_dir / "preset.yml").write_text(+ yaml.dump(+ {+ "schema_version": "1.0",+ "preset": {+ "id": "invalid-wrap",+ "name": "Invalid Wrap",+ "version": "1.0.0",+ "description": "Invalid wrapping constitution",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "constitution-template",+ "file": "templates/constitution-template.md",+ "strategy": "wrap",+ "description": "Invalid wrap",+ }+ ]+ },+ }+ )+ )++ manager = PresetManager(project_dir)+ install_constitution_sync_preset(manager)+ with pytest.warns(UserWarning, match="Failed to seed constitution"):+ manifest = manager.install_from_directory(preset_dir, "0.1.5")++ assert manifest.id == "invalid-wrap"+ assert manager.registry.is_installed("invalid-wrap")+++class TestPresetSkills(PresetArtifactTestHelpers):+ """Manager lifecycle behavior across skill and command mode changes."""++ def test_remove_after_partial_command_to_skills_toggle_keeps_skills_mode_agent_command_free(+ self, project_dir, temp_dir+ ):+ """Removal must not recreate a command file for a skills-mode agent.++ A partially failed commandβskills toggle leaves the active agent's+ stale ``registered_commands`` entry behind. Removing that preset+ records the agent in ``extra_agents`` for post-removal+ reconciliation, and ``register_commands_for_non_skill_agents``+ admits every ``extra_agents`` member even when the active-only+ ``only_agent`` guard excludes the agent β so the surviving+ lower-priority preset's command file was recreated for an agent+ now running in skills mode (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ lower_dir = self._create_command_preset(+ temp_dir, "stale-toggle-lower-preset", "speckit.plan",+ "Lower preset", "Lower body",+ )+ higher_dir = self._create_command_preset(+ temp_dir, "stale-toggle-higher-preset", "speckit.plan",+ "Higher preset", "Higher body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)++ command_file = copilot_commands_dir / "speckit.plan.agent.md"+ assert "Higher body" in command_file.read_text(encoding="utf-8"), (+ "sanity: command mode should have written the winning preset"+ )++ # Break the higher preset's installed source so its skill+ # replacement is silently skipped during the toggle β a genuine+ # partial commandβskills toggle that leaves the stale+ # registered_commands entry for copilot behind.+ (manager.presets_dir / "stale-toggle-higher-preset" / "commands" / "speckit.plan.md").unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ metadata = manager.registry.get("stale-toggle-higher-preset")+ assert "speckit.plan" in metadata["registered_commands"].get("copilot", []), (+ "sanity: the partial toggle must leave the stale command "+ "tracking behind"+ )++ manager.remove("stale-toggle-higher-preset")++ assert not command_file.exists(), (+ "removing the preset while copilot runs in skills mode must "+ "not recreate its command file from the surviving lower "+ "preset via the stale extra_agents entry (#2948)"+ )++ def test_remove_after_partial_skills_to_command_toggle_deletes_stale_skill(+ self, project_dir, temp_dir+ ):+ """Removal must delete, not restore, a command-mode agent's stale skill.++ The inverse partial toggle: a skillsβcommand conversion that could+ not replace one command leaves that skill tracked in+ ``registered_skills``. Removing the preset while the agent is now+ in command mode sent it through ``_unregister_skills()``, which+ restored a core/extension ``SKILL.md``, and ``extra_skills_dirs``+ then let ``_reconcile_skills`` reapply the surviving lower preset β+ leaving the active command-mode agent with a skill artifact it+ must not have (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ lower_dir = self._create_command_preset(+ temp_dir, "inverse-toggle-lower-preset", "speckit.plan",+ "Lower preset", "Lower body",+ )+ higher_dir = self._create_command_preset(+ temp_dir, "inverse-toggle-higher-preset", "speckit.plan",+ "Higher preset", "Higher body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)++ skill_dir = project_dir / ".github" / "skills" / "speckit-plan"+ assert (skill_dir / "SKILL.md").exists(), (+ "sanity: skills mode should have written the skill"+ )++ # Break the higher preset's installed source so its command+ # replacement never lands during the skillsβcommand toggle,+ # leaving the skill tracked for copilot.+ (manager.presets_dir / "inverse-toggle-higher-preset" / "commands" / "speckit.plan.md").unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ manager.register_enabled_presets_for_agent("copilot")++ metadata = manager.registry.get("inverse-toggle-higher-preset")+ registered_skills = metadata.get("registered_skills") or {}+ assert registered_skills.get("copilot"), (+ "sanity: the partial toggle must leave the stale skill "+ "tracking behind"+ )+ assert (skill_dir / "SKILL.md").exists(), (+ "sanity: the stale skill artifact must survive the partial toggle"+ )++ manager.remove("inverse-toggle-higher-preset")++ assert not skill_dir.exists(), (+ "removing the preset while copilot runs in command mode must "+ "delete the stale preset-owned skill instead of restoring core "+ "content or reapplying the surviving lower preset (#2948)"+ )++ def test_partial_skill_install_failure_rolls_back_persisted_writes(+ self, project_dir, temp_dir, monkeypatch+ ):+ """Install rollback must reload partial skill ownership before removal."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ (project_dir / ".github" / "agents").mkdir(parents=True)+ preset_dir = self._create_multi_command_preset(+ temp_dir,+ "partial-install-failure-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ original_read_text = Path.read_text++ def fail_plan_source(path, *args, **kwargs):+ if (+ path.name == "speckit.plan.md"+ and path.parent.name == "commands"+ and "partial-install-failure-preset" in path.parts+ ):+ raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid")+ return original_read_text(path, *args, **kwargs)++ monkeypatch.setattr(Path, "read_text", fail_plan_source)+ with pytest.raises(UnicodeDecodeError):+ manager.install_from_directory(preset_dir, "0.1.5")++ assert not manager.registry.is_installed(+ "partial-install-failure-preset"+ )+ skill_file = (+ project_dir+ / ".github"+ / "skills"+ / "speckit-specify"+ / "SKILL.md"+ )+ assert (+ not skill_file.exists()+ or "preset:partial-install-failure-preset"+ not in original_read_text(skill_file, encoding="utf-8")+ ), "rollback must not orphan a skill written before the later failure"+++class TestPresetPriorityBackwardsCompatibility:+ """Test backwards compatibility for presets installed before priority feature."""++ def test_legacy_preset_in_list_installed(self, project_dir, pack_dir):+ """list_installed returns priority=10 for legacy presets without priority field."""+ manager = PresetManager(project_dir)++ # Install preset normally+ manager.install_from_directory(pack_dir, "0.1.5")++ # Manually remove priority to simulate legacy preset+ pack_data = manager.registry.data["presets"]["test-pack"]+ del pack_data["priority"]+ manager.registry._save()++ # list_installed should still return priority=10+ installed = manager.list_installed()+ assert len(installed) == 1+ assert installed[0]["priority"] == 10+++class TestRemoveReconciliation:+ """Test that removing a preset re-registers the next layer's command."""++ def test_remove_restores_extension_command_subdir_paths_for_non_skill_agent(+ self, project_dir, temp_dir+ ):+ """When a preset override of an extension command is removed, the+ reconciled non-skill-agent command file should have the extension's+ own subdir references rewritten to their installed location (#2101),+ not left as bare, unresolvable paths."""+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\ndescription: Extension fakeext cmd\n---\n\n"+ "Read agents/control/commander.md for context.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ manager = PresetManager(project_dir)++ preset_dir = temp_dir / "ext-cmd-override"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\n\npreset override content\n"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-cmd-override",+ "name": "Ext Cmd Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_files = list(gemini_dir.glob("*fakeext*"))+ assert cmd_files, "Command file should exist in gemini dir"+ assert "preset override content" in cmd_files[0].read_text()++ manager.remove("ext-cmd-override")++ cmd_files = list(gemini_dir.glob("*fakeext*"))+ assert cmd_files, "Command file should still exist after removal"+ content = cmd_files[0].read_text()+ assert "preset override content" not in content+ assert ".specify/extensions/fakeext/agents/control/commander.md" in content+ assert "Read agents/control" not in content++ def test_remove_restores_lower_priority_command(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """After removing the top-priority preset, the next preset's command+ should be re-registered in agent directories."""+ manager = PresetManager(project_dir)++ # Create a gemini commands dir so reconciliation writes there+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ # Install a low-priority preset with a command+ lo_data = {**valid_pack_data}+ lo_data["preset"] = {+ **valid_pack_data["preset"],+ "id": "lo-preset",+ "name": "Lo",+ }+ lo_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }]+ }+ lo_dir = temp_dir / "lo-preset"+ lo_dir.mkdir()+ with open(lo_dir / "preset.yml", "w") as f:+ yaml.dump(lo_data, f)+ (lo_dir / "commands").mkdir()+ (lo_dir / "commands" / "speckit.specify.md").write_text(+ "---\ndescription: lo\n---\nLo content\n"+ )+ manager.install_from_directory(lo_dir, "0.1.5", priority=10)++ # Install a high-priority preset overriding the same command+ hi_data = {**valid_pack_data}+ hi_data["preset"] = {+ **valid_pack_data["preset"],+ "id": "hi-preset",+ "name": "Hi",+ }+ hi_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }]+ }+ hi_dir = temp_dir / "hi-preset"+ hi_dir.mkdir()+ with open(hi_dir / "preset.yml", "w") as f:+ yaml.dump(hi_data, f)+ (hi_dir / "commands").mkdir()+ (hi_dir / "commands" / "speckit.specify.md").write_text(+ "---\ndescription: hi\n---\nHi content\n"+ )+ manager.install_from_directory(hi_dir, "0.1.5", priority=1)++ # Verify the hi-preset's content is active in agent dir+ cmd_files = list(gemini_dir.glob("*specify*"))+ assert cmd_files, "Command file should exist in gemini dir"+ assert "Hi content" in cmd_files[0].read_text()++ # Remove the high-priority preset+ manager.remove("hi-preset")++ # The low-priority preset's command should now be in the resolution stack+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("speckit.specify", "command")+ assert len(layers) >= 1+ assert "lo-preset" in layers[0]["source"]++ # Verify on-disk agent command file switched to lo-preset content+ cmd_files = list(gemini_dir.glob("*specify*"))+ assert cmd_files, "Command file should still exist after removal"+ assert "Lo content" in cmd_files[0].read_text()diff --git a/tests/specify_cli/presets/test_manager_commands.py b/tests/specify_cli/presets/test_manager_commands.pynew file mode 100644index 000000000..d83ef12d1--- /dev/null+++ b/tests/specify_cli/presets/test_manager_commands.py@@ -0,0 +1,3160 @@+"""Tests for preset command artifacts in specify_cli.presets._manager_commands."""++from pathlib import Path++import pytest+import yaml++from specify_cli.presets import PresetManager+from tests.specify_cli.presets._helpers import (+ PresetArtifactTestHelpers,+ install_self_test_preset,+)+++class TestSelfTestPreset:+ """Command registration and removal using self-test."""++ def test_self_test_registers_commands_for_claude(self, project_dir):+ """Test that installing self-test registers skills in .claude/skills/."""+ # Create Claude skills directory to simulate Claude being set up+ claude_dir = project_dir / ".claude" / "skills"+ claude_dir.mkdir(parents=True)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ # Check the skill was registered+ cmd_file = claude_dir / "speckit-specify" / "SKILL.md"+ assert cmd_file.exists(), "Skill not registered in .claude/skills/"+ content = cmd_file.read_text()+ assert "self-test" in content+ assert "source:" in content # skill frontmatter includes metadata.source++ def test_self_test_registers_commands_for_gemini(self, project_dir):+ """Test that installing self-test registers commands in .gemini/commands/ as TOML."""+ # Create Gemini agent directory+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ # Check the command was registered in TOML format+ cmd_file = gemini_dir / "speckit.specify.toml"+ assert cmd_file.exists(), "Command not registered in .gemini/commands/"+ content = cmd_file.read_text()+ assert "prompt" in content # TOML format has a prompt field+ assert "{{args}}" in content # Gemini uses {{args}} placeholder++ def test_self_test_unregisters_commands_on_remove(self, project_dir):+ """Test that removing self-test cleans up registered commands."""+ claude_dir = project_dir / ".claude" / "skills"+ claude_dir.mkdir(parents=True)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ cmd_file = claude_dir / "speckit-specify" / "SKILL.md"+ assert cmd_file.exists()++ manager.remove("self-test")+ assert not cmd_file.exists(), "Command not cleaned up after preset removal"++ def test_self_test_no_commands_without_agent_dirs(self, project_dir):+ """Test that no commands are registered when no agent dirs exist."""+ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ metadata = manager.registry.get("self-test")+ assert metadata["registered_commands"] == {}++ def test_selfcontained_namespaced_command_scaffolds_without_extension(self, project_dir, temp_dir):+ """A preset shipping a self-contained ``speckit.<ns>.<cmd>`` command+ scaffolds even when no matching extension is installed.++ The command template ships its own body, so it is self-contained and+ must render just like a short ``speckit.<cmd>`` command. It is not+ dropped merely because ``.specify/extensions/fakeext/`` is absent.+ """+ claude_dir = project_dir / ".claude" / "skills"+ claude_dir.mkdir(parents=True)++ preset_dir = temp_dir / "ext-override-preset"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\nOverridden content"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-override",+ "name": "Ext Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ "description": "Override fakeext cmd",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Extension not installed, but the preset ships its own command body β+ # it must scaffold (as a native-skill SKILL.md for claude) and be+ # tracked in the preset's registered_commands.+ skill_file = claude_dir / "speckit-fakeext-cmd" / "SKILL.md"+ assert skill_file.exists(), "Self-contained namespaced command was dropped"+ metadata = manager.registry.get("ext-override")+ assert metadata["registered_commands"] != {}++ def test_extension_command_registered_when_extension_present(self, project_dir, temp_dir):+ """Test that extension command overrides ARE registered when the extension is installed."""+ claude_dir = project_dir / ".claude" / "skills"+ claude_dir.mkdir(parents=True)+ (project_dir / ".specify" / "extensions" / "fakeext").mkdir(parents=True)++ preset_dir = temp_dir / "ext-override-preset2"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\nOverridden content"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-override2",+ "name": "Ext Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ "description": "Override fakeext cmd",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_file = claude_dir / "speckit-fakeext-cmd" / "SKILL.md"+ assert cmd_file.exists(), "Skill not registered despite extension being present"+++class TestPresetSkills(PresetArtifactTestHelpers):+ """Preset command activation, reconciliation, and mode switching."""++ def test_preset_add_corrupted_init_options_fails_closed(self, project_dir, temp_dir):+ """Corrupted (but present) init-options.json must not back-fill every+ detected agent for preset command registration.++ Before the shared ``resolve_active_agent_for_registration`` fix,+ ``load_init_options`` returning ``{}`` for a corrupted file was+ indistinguishable from "no file at all", so ``_register_commands``+ treated it like a legacy pre-init-options project and registered+ the preset's command override for every detected agent (#2948).+ """+ init_options = project_dir / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text("{not valid json", encoding="utf-8")++ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "corrupt-init-preset", "speckit.specify",+ "Corrupt init test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ metadata = manager.registry.get("corrupt-init-preset")+ assert metadata.get("registered_commands") == {}, (+ "a corrupted init-options.json must fail closed, not "+ "back-fill every detected agent (#2948)"+ )+ assert not list(gemini_dir.glob("*specify*")), (+ "no command file should be written for any agent when "+ "init-options.json is corrupted"+ )++ def test_reconciliation_restricted_to_active_agent(self, project_dir, temp_dir):+ """Reconciliation after install/remove must also respect the+ single-active rule, not just the initial registration.++ ``_reconcile_composed_commands`` (invoked after+ ``install_from_directory``/``remove``) resolves composition winners+ via ``register_commands_for_non_skill_agents``, a separate code+ path from ``_register_commands``'s initial registration. Before the+ fix it ignored the active-agent restriction entirely and wrote the+ winning content for every detected non-skill agent, leaving+ untracked orphaned artifacts in inactive integrations (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ # A non-replace (append) strategy command forces reconciliation to+ # run register_commands_for_non_skill_agents for every non-skill+ # agent directory it detects.+ preset_dir = temp_dir / "reconcile-active-only"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.specify.md").write_text(+ "---\ndescription: Appended\nstrategy: append\n---\n\nAppended body\n",+ encoding="utf-8",+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "reconcile-active-only",+ "name": "Reconcile Active Only",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ "strategy": "append",+ }]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ assert not list(gemini_dir.glob("*specify*")), (+ "reconciliation must not write command files for a detected "+ "but inactive non-skill agent (#2948)"+ )++ def test_use_rescaffold_reconciles_project_override(self, project_dir, temp_dir):+ """``integration use``/``switch`` rescaffolding must reconcile the+ full priority stack, not just write each preset's own content.++ Project overrides are the highest-priority layer, above every+ preset. ``register_enabled_presets_for_agent`` (invoked by+ ``integration use``/``switch``) calls ``_register_commands`` for+ each enabled preset directly, the same as ``install_from_directory``+ β but unlike install/remove, it never followed up with+ ``_reconcile_composed_commands``. Before the fix, rescaffolding a+ newly activated agent could leave the preset's raw content in+ place instead of resolving the real winner (the project override)+ from the full stack (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True, exist_ok=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override specify\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "use-reconcile-preset", "speckit.specify",+ "Preset specify", "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Simulate `integration use gemini`: switch the active agent and+ # rescaffold enabled presets for it, mirroring what the CLI does.+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ manager.register_enabled_presets_for_agent("gemini")++ cmd_file = gemini_dir / "speckit.specify.toml"+ assert cmd_file.exists(), "sanity: gemini should get a command file at all"+ content = cmd_file.read_text()+ assert "Override body" in content, (+ "the project override must still win after rescaffold "+ "reconciliation, not the preset's raw content (#2948)"+ )+ assert "Preset body" not in content++ def test_hermes_rescaffold_reconciles_global_skill_output(+ self, project_dir, temp_dir, monkeypatch+ ):+ home = temp_dir / "home"+ home.mkdir()+ monkeypatch.setattr(Path, "home", lambda: home)+ (home / ".hermes" / "skills").mkdir(parents=True)+ self._write_init_options(project_dir, ai="hermes", ai_skills=True)+ (project_dir / ".hermes" / "skills").mkdir(parents=True)++ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True, exist_ok=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override specify\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ preset_dir = self._create_command_preset(+ temp_dir, "hermes-reconcile-preset", "speckit.specify",+ "Preset specify", "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.register_enabled_presets_for_agent("hermes")++ skill_file = (+ home / ".hermes" / "skills" / "speckit-specify" / "SKILL.md"+ )+ assert skill_file.exists()+ content = skill_file.read_text(encoding="utf-8")+ assert "Override body" in content+ assert "Preset body" not in content+ assert not list(+ (project_dir / ".hermes" / "skills").glob("speckit-*/SKILL.md")+ )++ (overrides_dir / "speckit.specify.md").unlink()+ assert manager.remove("hermes-reconcile-preset") is True+ if skill_file.exists():+ restored = skill_file.read_text(encoding="utf-8")+ assert "Override body" not in restored+ assert "Preset body" not in restored++ def test_rescaffold_persists_commands_before_fallible_skills_phase(+ self, project_dir, temp_dir+ ):+ """A failure in the skills phase must not lose track of command+ files the commands phase already wrote to disk.++ ``register_enabled_presets_for_agent`` computes both+ ``registered_commands`` and ``registered_skills`` and persists them+ together in a single ``registry.update()`` call after both phases+ run. If ``_register_skills`` raises, the whole per-preset ``try``+ block is caught and ``registry.update()`` is never reached β even+ though ``_register_commands`` already wrote a real command file to+ disk. That file becomes untracked and preset removal can no longer+ clean it up. ``install_from_directory`` avoids this by persisting+ ``registered_commands`` immediately after the commands phase,+ before starting the independently fallible skills phase; rescaffold+ must do the same (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ preset_dir = self._create_command_preset(+ temp_dir, "rescaffold-persist-preset", "speckit.specify",+ "Rescaffold persist test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Switch to gemini (a plain command-file agent, so _register_commands+ # writes a real file) and make the *skills* phase blow up.+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_commands_dir = project_dir / ".gemini" / "commands"+ gemini_commands_dir.mkdir(parents=True)++ from unittest.mock import patch++ with patch.object(+ PresetManager, "_register_skills",+ side_effect=RuntimeError("simulated skills failure"),+ ):+ manager.register_enabled_presets_for_agent("gemini")++ cmd_file = gemini_commands_dir / "speckit.specify.toml"+ assert cmd_file.exists(), (+ "sanity: the commands phase must have written the file before "+ "the skills phase raised"+ )++ metadata = manager.registry.get("rescaffold-persist-preset")+ assert metadata["registered_commands"].get("gemini"), (+ "registered_commands must be persisted immediately after the "+ "commands phase, not only after the (fallible) skills phase "+ "also succeeds β otherwise the file written above is untracked "+ "and preset removal can't clean it up (#2948)"+ )++ def test_rescaffold_reconciles_override_even_when_skills_phase_fails(+ self, project_dir, temp_dir+ ):+ """A project override must still win after rescaffold even if the+ independently-fallible skills phase raises for that preset.++ ``register_enabled_presets_for_agent`` only records a preset's+ command names into ``affected_cmd_names`` β the set later passed to+ ``_reconcile_composed_commands``/``_reconcile_skills`` β in the+ ``for tmpl in manifest.templates`` loop that runs *after*+ ``_register_skills`` inside the per-preset ``try`` block. If+ ``_register_skills`` raises, the per-preset ``except`` catches it+ and ``continue``s before that loop ever runs, so this preset's+ command names never make it into ``affected_cmd_names`` even though+ ``_register_commands`` already wrote its raw content to disk. The+ final reconciliation call is skipped for this preset entirely,+ leaving the raw preset content in place instead of the project+ override that should win (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True, exist_ok=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override specify\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "reconcile-despite-skills-failure", "speckit.specify",+ "Preset specify", "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Simulate `integration use gemini` with the skills phase failing+ # for this preset (e.g. a symlink/permission error unrelated to the+ # commands phase, which already succeeded).+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)++ from unittest.mock import patch++ with patch.object(+ PresetManager, "_register_skills",+ side_effect=RuntimeError("simulated skills failure"),+ ):+ manager.register_enabled_presets_for_agent("gemini")++ cmd_file = gemini_dir / "speckit.specify.toml"+ assert cmd_file.exists(), "sanity: gemini should get a command file at all"+ content = cmd_file.read_text()+ assert "Override body" in content, (+ "the project override must still win after rescaffold, even "+ "though this preset's skills phase raised β a fallible skills "+ "phase must not skip reconciliation for command writes that "+ "already succeeded (#2948)"+ )+ assert "Preset body" not in content++ def test_rescaffold_reconciles_partial_command_write_after_failure(+ self, project_dir, temp_dir, monkeypatch+ ):+ """A command written before _register_commands raises must still be+ included in final priority-stack reconciliation."""+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True, exist_ok=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override specify\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ preset_dir = self._create_command_preset(+ temp_dir,+ "partial-command-failure-preset",+ "speckit.specify",+ "Preset specify",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)+ cmd_file = gemini_dir / "speckit.specify.toml"++ def partial_register(manifest, pack_dir):+ cmd_file.write_text("Partially written preset body\n", encoding="utf-8")+ raise RuntimeError("simulated partial command failure")++ monkeypatch.setattr(manager, "_register_commands", partial_register)+ manager.register_enabled_presets_for_agent("gemini")++ content = cmd_file.read_text(encoding="utf-8")+ assert "Override body" in content+ assert "Partially written preset body" not in content++ def test_copilot_skills_mode_skips_command_registration(self, project_dir, temp_dir):+ """``integration use copilot`` with skills mode enabled must only+ write the SKILL.md mirror, not also copilot's static command file.++ Copilot is command-backed (``extension: ".agent.md"``), but when+ ``ai_skills`` is enabled its preset overrides are meant to render+ exclusively as skills via ``_register_skills``. Before the fix,+ ``_register_commands`` had no ``ai_skills`` guard (unlike the+ extensions path), so both a stale ``.agent.md`` command file and+ the ``SKILL.md`` mirror were written for the same override (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "copilot-skills-preset", "speckit.specify",+ "Copilot skills test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ assert not list(copilot_commands_dir.glob("*specify*")), (+ "command-mode and skills-mode artifacts are mutually exclusive: "+ "no .agent.md command file should be written when copilot is "+ "running in skills mode (#2948)"+ )+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:copilot-skills-preset" in skill_file.read_text()++ def test_rescaffold_toggle_command_to_skills_removes_stale_command_file(+ self, project_dir, temp_dir+ ):+ """Toggling the *same* agent from command mode to skills mode must+ remove the stale command-mode artifact, not just add the new one.++ Copilot stays the active agent throughout (``integration upgrade+ copilot`` after flipping ``ai_skills``, not a switch to a different+ agent). Before the fix, ``_register_commands``'s ``ai_skills`` guard+ made rescaffold a no-op for the commands phase once skills mode was+ on, leaving the previously written ``.agent.md`` file and its+ ``registered_commands`` entry behind even though ``_register_skills``+ went on to also write the ``SKILL.md`` mirror β violating the+ command/skill mutual-exclusion invariant this PR otherwise enforces+ (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "toggle-cmd-to-skill-preset", "speckit.specify",+ "Toggle test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ assert cmd_file.exists(), (+ "sanity: command mode should have written copilot's command file"+ )+ metadata = manager.registry.get("toggle-cmd-to-skill-preset")+ assert metadata["registered_commands"].get("copilot"), (+ "sanity: the command-mode write should be tracked for copilot"+ )++ # Flip ai_skills on for the *same* active agent and rescaffold, as+ # `integration upgrade copilot` would after the mode toggle.+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert not cmd_file.exists(), (+ "the stale command-mode file must be removed once copilot has "+ "toggled to skills mode for the same agent (#2948)"+ )+ metadata = manager.registry.get("toggle-cmd-to-skill-preset")+ assert not metadata["registered_commands"].get("copilot"), (+ "registered_commands must stop tracking copilot once its "+ "artifact has been unregistered, or removal will try to clean "+ "up a file that no longer exists (#2948)"+ )+ skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"+ assert "preset:toggle-cmd-to-skill-preset" in skill_file.read_text(), (+ "sanity: the new skills-mode artifact should still be written"+ )++ def test_rescaffold_scaffolds_selfcontained_namespaced_commands(+ self, project_dir, temp_dir+ ):+ """A self-contained ``speckit.<ns>.<cmd>`` preset command scaffolds and+ survives rescaffold, even when no matching extension is installed.++ The preset ships the command body itself, so it is materialized just+ like a short ``speckit.<cmd>`` command β both at install and through a+ later reconciliation/rescaffold pass. It is not dropped by the+ ``speckit.<ns>.<cmd>`` name shape (#4076).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "ext-scoped-preset", "speckit.git.feature",+ "Ext override", "ext body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ ext_cmd = commands_dir / "speckit.git.feature.agent.md"+ assert ext_cmd.exists(), (+ "sanity: install must scaffold a self-contained namespaced command "+ "even when its like-named extension isn't installed"+ )++ manager.register_enabled_presets_for_agent("copilot")++ assert ext_cmd.exists(), (+ "rescaffold must keep the self-contained namespaced command"+ )+ metadata = manager.registry.get("ext-scoped-preset")+ assert (metadata.get("registered_commands") or {}).get("copilot")++ def test_rescaffold_scaffolds_selfcontained_namespaced_skills(+ self, project_dir, temp_dir+ ):+ """A self-contained ``speckit.<ns>.<cmd>`` preset command renders its+ skill even when no matching extension is installed."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skills_dir = project_dir / ".github" / "skills"+ skills_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir,+ "ext-scoped-skill-preset",+ "speckit.git.feature",+ "Ext override",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_name = "speckit-git-feature"+ skill_file = skills_dir / skill_name / "SKILL.md"+ assert skill_file.exists(), (+ "install must render a self-contained namespaced command's skill "+ "even when its like-named extension isn't installed"+ )++ manager.register_enabled_presets_for_agent("copilot")++ assert skill_file.exists(), (+ "rescaffold must keep the self-contained namespaced command's skill"+ )++ def test_uncomposable_wrap_command_skips_skill_in_skills_mode(+ self, project_dir, temp_dir+ ):+ """A wrap command with no base layer must not materialize a broken+ skill in skills mode.++ When ``_register_commands`` skips an uncomposable wrap command (no+ base to compose onto β e.g. the command it wraps comes from an+ uninstalled extension), ``_register_skills`` must skip it too. Before+ this fix, skills mode fell back to the raw preset body and wrote a+ SKILL.md containing a literal ``{CORE_TEMPLATE}`` placeholder.+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skills_dir = project_dir / ".github" / "skills"+ skills_dir.mkdir(parents=True)++ preset_dir = temp_dir / "uncomposable-wrap"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ # speckit.git.feature has no core command template and no installed+ # extension, so there is no base layer to wrap.+ (preset_dir / "commands" / "speckit.git.feature.md").write_text(+ "---\ndescription: Wrap\nstrategy: wrap\n---\n\n"+ "wrap start\n{CORE_TEMPLATE}\nwrap end\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "uncomposable-wrap",+ "name": "uncomposable-wrap",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.git.feature",+ "file": "commands/speckit.git.feature.md",+ "strategy": "wrap",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="no base command layer"):+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-git-feature" / "SKILL.md"+ assert not skill_file.exists(), (+ "an uncomposable wrap command must not be rendered as a skill"+ )+ # Belt-and-suspenders: no artifact anywhere may leak the raw placeholder.+ leaked = [+ p for p in skills_dir.rglob("*")+ if p.is_file() and "{CORE_TEMPLATE}" in p.read_text(encoding="utf-8")+ ]+ assert not leaked, f"literal {{CORE_TEMPLATE}} leaked into {leaked}"++ def test_same_mode_partial_command_rescaffold_keeps_skipped_tracking(+ self, project_dir, temp_dir+ ):+ """A partial command refresh must keep still-live skipped artifacts tracked."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)+ preset_dir = self._create_multi_command_preset(+ temp_dir,+ "same-mode-partial-command-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ installed_dir = manager.presets_dir / "same-mode-partial-command-preset"+ (installed_dir / "commands" / "speckit.plan.md").unlink()+ manager.register_enabled_presets_for_agent("copilot")++ metadata = manager.registry.get("same-mode-partial-command-preset")+ assert set(metadata["registered_commands"]["copilot"]) == {+ "speckit.specify",+ "speckit.plan",+ }+ assert (commands_dir / "speckit.plan.agent.md").exists()++ def test_same_mode_partial_skill_rescaffold_keeps_skipped_tracking(+ self, project_dir, temp_dir+ ):+ """A partial skill refresh must keep still-live skipped artifacts tracked."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")+ self._create_skill(skills_dir, "speckit-plan")+ preset_dir = self._create_multi_command_preset(+ temp_dir,+ "same-mode-partial-skill-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ installed_dir = manager.presets_dir / "same-mode-partial-skill-preset"+ (installed_dir / "commands" / "speckit.plan.md").unlink()+ manager.register_enabled_presets_for_agent("copilot")++ metadata = manager.registry.get("same-mode-partial-skill-preset")+ assert set(metadata["registered_skills"]["copilot"]) == {+ "speckit-specify",+ "speckit-plan",+ }++ def test_toggle_command_to_skills_preserves_old_command_on_skills_failure(+ self, project_dir, temp_dir, monkeypatch+ ):+ """A command->skills toggle must not destroy the old command+ artifact before the new skill registration has actually succeeded.++ Before the fix, the stale command-mode file/tracking was+ unregistered unconditionally as soon as ``_register_commands``'s+ ``ai_skills`` guard made the commands phase a no-op β regardless+ of whether the subsequent, independently-fallible+ ``_register_skills()`` call actually succeeded. If skills raises+ (e.g. a transient I/O error), the per-preset exception handler+ just logs and continues, leaving neither the old command file+ nor a new skill file β the preset's command override vanishes+ entirely from copilot until the next successful rescaffold+ (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "toggle-failure-preset", "speckit.specify",+ "Toggle failure test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ assert cmd_file.exists(), (+ "sanity: command mode should have written copilot's command file"+ )+ metadata = manager.registry.get("toggle-failure-preset")+ assert metadata["registered_commands"].get("copilot"), (+ "sanity: the command-mode write should be tracked for copilot"+ )++ # Flip ai_skills on for the *same* active agent and rescaffold, as+ # `integration upgrade copilot` would, but with skills registration+ # injected to fail.+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ def _raise_register_skills(*args, **kwargs):+ raise OSError("simulated skills-phase failure")++ monkeypatch.setattr(manager, "_register_skills", _raise_register_skills)+ manager.register_enabled_presets_for_agent("copilot")++ assert cmd_file.exists(), (+ "the old command-mode artifact must survive when the "+ "replacement skills registration fails β deleting it before "+ "the new artifact is confirmed leaves neither in place (#2948)"+ )+ metadata = manager.registry.get("toggle-failure-preset")+ assert metadata["registered_commands"].get("copilot"), (+ "registered_commands must keep tracking copilot's still-live "+ "command file when the skills replacement failed, or a later "+ "removal/rescaffold will believe there is nothing to clean up "+ "even though the file is still on disk (#2948)"+ )++ def test_toggle_command_to_skills_empty_result_preserves_old_command(+ self, project_dir, temp_dir+ ):+ """A non-raising but empty skills result must not delete the old command.++ Before the fix, the stale command-mode artifact was retired as+ soon as ``_register_skills()`` completed without raising β+ regardless of whether it actually wrote anything for this agent.+ Deleting the preset's own command source file (simulating a+ missing/corrupted override) makes ``_register_skills`` return+ ``{}`` for copilot without raising at all, which must leave the+ old command file and its tracking untouched (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "toggle-empty-result-preset", "speckit.specify",+ "Toggle empty-result test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ assert cmd_file.exists(), (+ "sanity: command mode should have written copilot's command file"+ )++ # Remove the *installed* copy of the preset's source file (not the+ # original temp source) so _register_skills can find nothing to+ # render β a real "missing source" case, not an exception β leaving+ # registered_skills empty for copilot.+ (manager.presets_dir / "toggle-empty-result-preset" / "commands" / "speckit.specify.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert cmd_file.exists(), (+ "an empty (non-raising) skills registration result must not "+ "cause the old command-mode artifact to be deleted (#2948)"+ )+ metadata = manager.registry.get("toggle-empty-result-preset")+ assert metadata["registered_commands"].get("copilot"), (+ "registered_commands must keep tracking copilot's still-live "+ "command file when nothing was actually replaced (#2948)"+ )+ skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"+ assert not skill_file.exists(), (+ "sanity: no skill should have been written when the source "+ "was missing"+ )++ def test_toggle_command_to_skills_partial_result_only_removes_replaced_command(+ self, project_dir, temp_dir+ ):+ """Only the command whose skill replacement actually landed is retired.++ A two-command preset where one command's source file goes missing+ right before the toggle: ``_register_skills`` genuinely returns a+ partial result (one name present, one silently skipped) without+ raising. The command whose skill was written must be retired; the+ other must keep both its old command file and its registry+ tracking, since no replacement for it actually landed (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_multi_command_preset(+ temp_dir, "toggle-partial-result-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ specify_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ plan_cmd_file = copilot_commands_dir / "speckit.plan.agent.md"+ assert specify_cmd_file.exists() and plan_cmd_file.exists(), (+ "sanity: command mode should have written both command files"+ )+ metadata = manager.registry.get("toggle-partial-result-preset")+ assert set(metadata["registered_commands"].get("copilot", [])) == {+ "speckit.specify", "speckit.plan",+ }, "sanity: both commands should be tracked for copilot"++ # Remove only the plan command's *installed* source so its skill+ # replacement is silently skipped (missing source), while+ # specify's succeeds β a genuine partial result, not an injected+ # exception.+ (manager.presets_dir / "toggle-partial-result-preset" / "commands" / "speckit.plan.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert not specify_cmd_file.exists(), (+ "the specify command's old artifact must be retired since its "+ "skill replacement actually landed (#2948)"+ )+ assert plan_cmd_file.exists(), (+ "the plan command's old artifact must survive since its skill "+ "replacement never landed (missing source) (#2948)"+ )+ metadata = manager.registry.get("toggle-partial-result-preset")+ tracked_commands = metadata["registered_commands"].get("copilot", [])+ assert "speckit.specify" not in tracked_commands, (+ "specify must stop being tracked as a command once its "+ "artifact has been unregistered (#2948)"+ )+ assert "speckit.plan" in tracked_commands, (+ "plan must keep being tracked as a command since its old "+ "artifact is still on disk (#2948)"+ )+ specify_skill_file = (+ project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"+ )+ assert "preset:toggle-partial-result-preset" in specify_skill_file.read_text(), (+ "sanity: specify's new skill artifact should exist"+ )+ plan_skill_file = project_dir / ".github" / "skills" / "speckit-plan"+ assert not plan_skill_file.exists(), (+ "sanity: no skill should have been written for plan since its "+ "source was missing"+ )++ def test_lower_priority_skill_does_not_remove_failed_winner_command(+ self, project_dir, temp_dir+ ):+ """Only a successfully rendered winning layer may retire a command."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ lower_dir = self._create_command_preset(+ temp_dir,+ "lower-toggle-preset",+ "speckit.specify",+ "Lower preset",+ "Lower body",+ )+ higher_dir = self._create_command_preset(+ temp_dir,+ "higher-toggle-preset",+ "speckit.specify",+ "Higher preset",+ "Higher body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)++ command_file = commands_dir / "speckit.specify.agent.md"+ assert "Higher body" in command_file.read_text(encoding="utf-8")++ higher_source = (+ manager.presets_dir+ / "higher-toggle-preset"+ / "commands"+ / "speckit.specify.md"+ )+ higher_source.unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ manager.register_enabled_presets_for_agent("copilot")++ assert command_file.exists(), (+ "a lower-priority skill replacement must not remove the existing "+ "higher-priority command when the winning layer did not render"+ )+ assert "Higher body" in command_file.read_text(encoding="utf-8")++ higher_source.write_text(+ "---\ndescription: Higher preset\n---\n\nHigher body\n",+ encoding="utf-8",+ )+ manager.register_enabled_presets_for_agent("copilot")++ assert not command_file.exists(), (+ "the old command should be retired after the winning skill "+ "layer renders successfully"+ )+ for preset_id in ("lower-toggle-preset", "higher-toggle-preset"):+ metadata = manager.registry.get(preset_id)+ assert not metadata["registered_commands"].get("copilot"), (+ "all layers sharing the retired command output must drop "+ "their stale command tracking"+ )++ def test_successful_winner_without_stale_tracking_retires_lower_command(+ self, project_dir, temp_dir+ ):+ """Winner success is independent of whether that layer tracked a command."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ lower_dir = self._create_command_preset(+ temp_dir,+ "lower-command-preset",+ "speckit.specify",+ "Lower preset",+ "Lower body",+ )+ higher_dir = self._create_command_preset(+ temp_dir,+ "higher-skill-preset",+ "speckit.specify",+ "Higher preset",+ "Higher body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)++ command_file = commands_dir / "speckit.specify.agent.md"+ assert command_file.exists()++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)+ higher_metadata = manager.registry.get("higher-skill-preset")+ assert not higher_metadata["registered_commands"].get("copilot")++ manager.register_enabled_presets_for_agent("copilot")++ assert not command_file.exists(), (+ "a successfully rendered winning skill must retire a lower "+ "layer's stale command even when the winner never tracked one"+ )+ lower_metadata = manager.registry.get("lower-command-preset")+ assert not lower_metadata["registered_commands"].get("copilot")++ def test_lower_priority_command_does_not_remove_failed_winner_skill(+ self, project_dir, temp_dir+ ):+ """Only a successfully rendered winning command may retire a skill."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ lower_dir = self._create_command_preset(+ temp_dir,+ "lower-skill-preset",+ "speckit.specify",+ "Lower preset",+ "Lower body",+ )+ higher_dir = self._create_command_preset(+ temp_dir,+ "higher-command-preset",+ "speckit.specify",+ "Higher preset",+ "Higher body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)++ skill_file = (+ project_dir+ / ".github"+ / "skills"+ / "speckit-specify"+ / "SKILL.md"+ )+ assert "Higher body" in skill_file.read_text(encoding="utf-8")++ higher_source = (+ manager.presets_dir+ / "higher-command-preset"+ / "commands"+ / "speckit.specify.md"+ )+ higher_source.unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)++ manager.register_enabled_presets_for_agent("copilot")++ assert skill_file.exists(), (+ "a lower-priority command replacement must not remove the "+ "existing higher-priority skill when the winner did not render"+ )+ assert "Higher body" in skill_file.read_text(encoding="utf-8")++ higher_source.write_text(+ "---\ndescription: Higher preset\n---\n\nHigher body\n",+ encoding="utf-8",+ )+ manager.register_enabled_presets_for_agent("copilot")++ assert not skill_file.exists(), (+ "the old skill should be retired after the winning command "+ "layer renders successfully"+ )+ for preset_id in ("lower-skill-preset", "higher-command-preset"):+ metadata = manager.registry.get(preset_id)+ assert not metadata["registered_skills"].get("copilot"), (+ "all layers sharing the retired skill output must drop "+ "their stale skill tracking"+ )++ def test_project_override_command_retires_stale_preset_skill(+ self, project_dir, temp_dir+ ):+ """A reconciled project override can replace a stale preset skill."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir,+ "override-toggle-preset",+ "speckit.specify",+ "Preset",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = (+ project_dir+ / ".github"+ / "skills"+ / "speckit-specify"+ / "SKILL.md"+ )+ assert skill_file.exists()++ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Project override\n---\n\nOverride body\n",+ encoding="utf-8",+ )+ (+ manager.presets_dir+ / "override-toggle-preset"+ / "commands"+ / "speckit.specify.md"+ ).unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)++ manager.register_enabled_presets_for_agent("copilot")++ command_file = commands_dir / "speckit.specify.agent.md"+ assert "Override body" in command_file.read_text(encoding="utf-8")+ assert not skill_file.exists(), (+ "the stale preset skill must be retired once the project "+ "override command is successfully reconciled"+ )+ metadata = manager.registry.get("override-toggle-preset")+ assert not metadata["registered_skills"].get("copilot")++ def test_project_override_command_retires_reconciled_override_skill(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir,+ "reconciled-override-toggle-preset",+ "speckit.specify",+ "Preset",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Project override\n---\n\nOverride body\n",+ encoding="utf-8",+ )+ (+ manager.presets_dir+ / "reconciled-override-toggle-preset"+ / "commands"+ / "speckit.specify.md"+ ).unlink()++ manager.register_enabled_presets_for_agent("copilot")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "override:speckit.specify" in skill_file.read_text(+ encoding="utf-8"+ )++ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ manager.register_enabled_presets_for_agent("copilot")++ assert "Override body" in (+ commands_dir / "speckit.specify.agent.md"+ ).read_text(encoding="utf-8")+ assert not skill_file.exists()+ metadata = manager.registry.get(+ "reconciled-override-toggle-preset"+ )+ assert not metadata["registered_skills"].get("copilot")++ def test_project_override_skill_retires_stale_preset_command(+ self, project_dir, temp_dir+ ):+ """A reconciled override skill may retire a stale preset command."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir,+ "override-skill-toggle-preset",+ "speckit.specify",+ "Preset",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ command_file = commands_dir / "speckit.specify.agent.md"+ assert command_file.exists()+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")+ manager.registry.update(+ "override-skill-toggle-preset",+ {"registered_skills": {"copilot": ["speckit-specify"]}},+ )++ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Project override\n---\n\nOverride body\n",+ encoding="utf-8",+ )+ (+ manager.presets_dir+ / "override-skill-toggle-preset"+ / "commands"+ / "speckit.specify.md"+ ).unlink()+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ manager.register_enabled_presets_for_agent("copilot")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "Override body" in skill_file.read_text(encoding="utf-8")+ assert not command_file.exists(), (+ "the stale preset command must be retired after the project "+ "override skill is successfully reconciled"+ )+ metadata = manager.registry.get("override-skill-toggle-preset")+ assert not metadata["registered_commands"].get("copilot")++ def test_toggle_skills_to_command_empty_result_preserves_old_skill(+ self, project_dir, temp_dir+ ):+ """A non-raising but empty command result must not delete the old skill.++ Mirror image of the empty-result command->skills case: deleting the+ preset's own source file makes ``_register_commands`` return ``{}``+ for copilot without raising, which must leave the old SKILL.md and+ its tracking untouched (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "toggle-skill-empty-result-preset", "speckit.specify",+ "Toggle empty-result test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:toggle-skill-empty-result-preset" in skill_file.read_text(), (+ "sanity: skills mode should have written the SKILL.md mirror"+ )++ # Remove the preset's own *installed* source file so+ # _register_commands can find nothing to render β a real "missing+ # source" case, not an exception β leaving registered_commands+ # empty for copilot.+ (manager.presets_dir / "toggle-skill-empty-result-preset" / "commands" / "speckit.specify.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ manager.register_enabled_presets_for_agent("copilot")++ assert "preset:toggle-skill-empty-result-preset" in skill_file.read_text(), (+ "an empty (non-raising) command registration result must not "+ "cause the old skills-mode artifact to be deleted/reverted "+ "(#2948)"+ )+ metadata = manager.registry.get("toggle-skill-empty-result-preset")+ assert "speckit-specify" in metadata["registered_skills"].get("copilot", []), (+ "registered_skills must keep tracking copilot's still-live "+ "skill file when nothing was actually replaced (#2948)"+ )++ def test_toggle_skills_to_command_partial_result_only_removes_replaced_skill(+ self, project_dir, temp_dir+ ):+ """Only the skill whose command replacement actually landed is retired.++ Mirror image of the partial-result command->skills case: a+ two-command preset where one command's source file goes missing+ right before the toggle, so ``_register_commands`` genuinely+ returns a partial result. The skill whose command was written+ must be retired; the other must keep both its old SKILL.md and+ its registry tracking, since no replacement for it landed (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")+ self._create_skill(skills_dir, "speckit-plan")++ # A core template lets the retired skill restore to core content+ # instead of being removed entirely (it has nothing else to fall+ # back to), matching _unregister_skills's behaviour elsewhere.+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ preset_dir = self._create_multi_command_preset(+ temp_dir, "toggle-skill-partial-result-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ specify_skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ plan_skill_file = skills_dir / "speckit-plan" / "SKILL.md"+ assert "preset:toggle-skill-partial-result-preset" in specify_skill_file.read_text()+ assert "preset:toggle-skill-partial-result-preset" in plan_skill_file.read_text()+ metadata = manager.registry.get("toggle-skill-partial-result-preset")+ assert set(metadata["registered_skills"].get("copilot", [])) == {+ "speckit-specify", "speckit-plan",+ }, "sanity: both skills should be tracked for copilot"++ # Remove only the plan command's *installed* source so its command+ # replacement is silently skipped (missing source), while+ # specify's succeeds.+ (manager.presets_dir / "toggle-skill-partial-result-preset" / "commands" / "speckit.plan.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ manager.register_enabled_presets_for_agent("copilot")++ assert "preset:toggle-skill-partial-result-preset" not in specify_skill_file.read_text(), (+ "the specify skill's old artifact must be retired/reverted "+ "since its command replacement actually landed (#2948)"+ )+ assert "preset:toggle-skill-partial-result-preset" in plan_skill_file.read_text(), (+ "the plan skill's old artifact must survive since its command "+ "replacement never landed (missing source) (#2948)"+ )+ metadata = manager.registry.get("toggle-skill-partial-result-preset")+ tracked_skills = metadata["registered_skills"].get("copilot", [])+ assert "speckit-specify" not in tracked_skills, (+ "specify must stop being tracked as a skill once its artifact "+ "has been unregistered/reverted (#2948)"+ )+ assert "speckit-plan" in tracked_skills, (+ "plan must keep being tracked as a skill since its old "+ "artifact is still on disk (#2948)"+ )+ assert (copilot_commands_dir / "speckit.specify.agent.md").exists(), (+ "sanity: specify's new command artifact should exist"+ )++ def test_toggle_command_to_skills_retires_alias_group_when_primary_skill_lands(+ self, project_dir, temp_dir+ ):+ """A command's aliases must be retired together with its primary+ once the primary's skill replacement lands.++ ``CommandRegistrar.register_commands()`` tracks and returns+ primary + alias names flattened together, but ``_register_skills()``+ only ever renders/returns the *primary* command name's skill. The+ alias's own name run through ``_skill_names_for_command()`` never+ matches anything real, so without grouping by primary, the alias+ command artifact and its tracking entry would survive forever even+ after mutual exclusion is otherwise enforced for the primary (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_multi_command_preset_with_aliases(+ temp_dir, "alias-group-success-preset",+ [("speckit.specify", ["speckit.spec"])],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ primary_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ alias_cmd_file = copilot_commands_dir / "speckit.spec.agent.md"+ assert primary_cmd_file.exists() and alias_cmd_file.exists(), (+ "sanity: command mode should have written both the primary "+ "and alias command files"+ )+ metadata = manager.registry.get("alias-group-success-preset")+ assert set(metadata["registered_commands"].get("copilot", [])) == {+ "speckit.specify", "speckit.spec",+ }, "sanity: both primary and alias should be tracked for copilot"++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert not primary_cmd_file.exists(), (+ "the primary's old command artifact must be retired once its "+ "skill replacement lands (#2948)"+ )+ assert not alias_cmd_file.exists(), (+ "the alias's old command artifact must be retired together "+ "with its primary once the primary's skill replacement lands "+ "(#2948)"+ )+ metadata = manager.registry.get("alias-group-success-preset")+ registered_commands = metadata.get("registered_commands", {})+ assert not registered_commands.get("copilot"), (+ "neither the primary nor the alias should remain tracked as "+ "commands once both artifacts are retired (#2948)"+ )+ skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"+ assert skill_file.exists(), "sanity: the primary's skill should have been written"++ def test_toggle_command_to_skills_keeps_alias_group_when_primary_skill_missing(+ self, project_dir, temp_dir+ ):+ """A command's aliases must survive together with its primary when+ the primary's skill replacement never lands.++ Mirror image of the group-retirement case: deleting the preset's+ own installed command source makes ``_register_skills`` genuinely+ return nothing for ``speckit.specify``, so neither the primary nor+ its alias have a real replacement β both old command artifacts and+ their tracking must survive (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_multi_command_preset_with_aliases(+ temp_dir, "alias-group-failure-preset",+ [("speckit.specify", ["speckit.spec"])],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ primary_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ alias_cmd_file = copilot_commands_dir / "speckit.spec.agent.md"+ assert primary_cmd_file.exists() and alias_cmd_file.exists(), (+ "sanity: command mode should have written both the primary "+ "and alias command files"+ )++ # Remove the installed source so _register_skills can find nothing+ # to render for the primary β a real "missing source" case.+ (manager.presets_dir / "alias-group-failure-preset" / "commands" / "speckit.specify.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert primary_cmd_file.exists(), (+ "the primary's old command artifact must survive since its "+ "skill replacement never landed (#2948)"+ )+ assert alias_cmd_file.exists(), (+ "the alias's old command artifact must survive together with "+ "its primary since neither has a real replacement (#2948)"+ )+ metadata = manager.registry.get("alias-group-failure-preset")+ assert set(metadata["registered_commands"].get("copilot", [])) == {+ "speckit.specify", "speckit.spec",+ }, (+ "both the primary and alias must keep being tracked since "+ "nothing was actually replaced (#2948)"+ )+ skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"+ assert not skill_file.exists(), (+ "sanity: no skill should have been written when the source "+ "was missing"+ )++ def test_toggle_command_to_skills_partial_multi_group_only_retires_successful_group(+ self, project_dir, temp_dir+ ):+ """With two independent alias groups, only the group whose primary+ skill actually lands is retired; the other survives intact.++ A preset with two commands (``speckit.specify`` with alias+ ``speckit.spec``, and ``speckit.plan`` with alias+ ``speckit.plan-alt``) where only ``speckit.plan``'s installed+ source goes missing: ``speckit.specify``'s group (primary + alias)+ must be fully retired, while ``speckit.plan``'s entire group+ (primary + alias) must survive together, since grouping is+ per-primary, not per-individual-name (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_multi_command_preset_with_aliases(+ temp_dir, "alias-group-partial-preset",+ [+ ("speckit.specify", ["speckit.spec"]),+ ("speckit.plan", ["speckit.plan-alt"]),+ ],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ specify_cmd = copilot_commands_dir / "speckit.specify.agent.md"+ spec_alias_cmd = copilot_commands_dir / "speckit.spec.agent.md"+ plan_cmd = copilot_commands_dir / "speckit.plan.agent.md"+ plan_alias_cmd = copilot_commands_dir / "speckit.plan-alt.agent.md"+ assert all(+ f.exists() for f in (specify_cmd, spec_alias_cmd, plan_cmd, plan_alias_cmd)+ ), "sanity: command mode should have written all four command files"++ # Remove only plan's installed source so its group's skill+ # replacement is silently skipped, while specify's group succeeds.+ (manager.presets_dir / "alias-group-partial-preset" / "commands" / "speckit.plan.md").unlink()++ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ manager.register_enabled_presets_for_agent("copilot")++ assert not specify_cmd.exists() and not spec_alias_cmd.exists(), (+ "specify's whole group (primary + alias) must be retired "+ "since its skill replacement landed (#2948)"+ )+ assert plan_cmd.exists() and plan_alias_cmd.exists(), (+ "plan's whole group (primary + alias) must survive together "+ "since its skill replacement never landed (#2948)"+ )+ metadata = manager.registry.get("alias-group-partial-preset")+ tracked_commands = set(metadata["registered_commands"].get("copilot", []))+ assert tracked_commands == {"speckit.plan", "speckit.plan-alt"}, (+ "only plan's group should remain tracked as commands; "+ "specify's group must be fully untracked (#2948)"+ )++ def test_rescaffold_toggle_skills_to_command_removes_stale_skill_file(+ self, project_dir, temp_dir+ ):+ """Toggling the *same* agent from skills mode to command mode must+ remove the stale skills-mode artifact, not just add the new one.++ Mirror image of the command-to-skills toggle: once ``ai_skills`` is+ turned off for copilot (still the active agent), ``_get_skills_dir``+ stops resolving a skills directory for it, so ``_register_skills``+ becomes a no-op β but the ``SKILL.md`` written while skills mode was+ on, and its ``registered_skills`` entry, were left behind even+ though ``_register_commands`` went on to (re)write the ``.agent.md``+ command file, again breaking mutual exclusion (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # A core template lets the stale skill restore to core content+ # (instead of being removed entirely, since it has nothing to fall+ # back to), matching how `_unregister_skills` behaves elsewhere.+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ preset_dir = self._create_command_preset(+ temp_dir, "toggle-skill-to-cmd-preset", "speckit.specify",+ "Toggle test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:toggle-skill-to-cmd-preset" in skill_file.read_text(), (+ "sanity: skills mode should have written the SKILL.md mirror"+ )+ metadata = manager.registry.get("toggle-skill-to-cmd-preset")+ assert metadata["registered_skills"].get("copilot"), (+ "sanity: the skills-mode write should be tracked for copilot"+ )++ # Flip ai_skills off for the *same* active agent and rescaffold, as+ # `integration upgrade copilot` would after the mode toggle.+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ manager.register_enabled_presets_for_agent("copilot")++ restored_content = skill_file.read_text()+ assert "preset:toggle-skill-to-cmd-preset" not in restored_content, (+ "the stale skills-mode artifact must be reverted once copilot "+ "has toggled to command mode for the same agent (#2948)"+ )+ assert "Core specify body" in restored_content, (+ "sanity: the skill should fall back to core content, not just "+ "lose the preset's override"+ )+ metadata = manager.registry.get("toggle-skill-to-cmd-preset")+ assert not metadata["registered_skills"].get("copilot"), (+ "registered_skills must stop tracking copilot once its "+ "artifact has been unregistered/restored (#2948)"+ )+ cmd_file = copilot_commands_dir / "speckit.specify.agent.md"+ assert cmd_file.exists(), (+ "sanity: the new command-mode artifact should still be written"+ )+ assert "preset body" in cmd_file.read_text()++ def test_native_skill_activation_recreates_deleted_skills_root(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ preset_dir = self._create_command_preset(+ temp_dir,+ "native-root-recovery-preset",+ "speckit.specify",+ "Native root recovery",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ codex_skills_dir = project_dir / ".agents" / "skills"+ assert not codex_skills_dir.exists()+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")++ skill_file = codex_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:native-root-recovery-preset" in skill_file.read_text()+ metadata = manager.registry.get("native-root-recovery-preset")+ assert "speckit.specify" in metadata["registered_commands"]["codex"]++ def test_rescaffold_migrates_legacy_flat_list_registered_skills(+ self, project_dir, temp_dir+ ):+ """Rescaffolding a preset with a legacy flat-list ``registered_skills``+ entry must persist the migrated per-agent dict even when the+ rescaffolded skill names are unchanged from before.++ ``_normalize_registered_skills`` converts a legacy flat ``List[str]``+ (predating per-agent provenance) into ``{agent_name: [...]}`` in+ memory, but the persistence check compared only the *normalized*+ ``merged_skills`` against the *normalized* ``existing_skills`` β+ both derived from the same raw legacy list. When the freshly+ registered names are identical to what the legacy list already+ held (the common case: nothing about the preset or skill actually+ changed), that comparison is a no-op and ``registry.update()`` is+ skipped, leaving the *raw* on-disk value as the un-migrated flat+ list. A later switch to a different skill-mode agent and removal+ then follows the legacy best-effort restore path (only the+ currently active agent's directory) instead of the per-agent+ provenance path, orphaning the first agent's override (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "legacy-skills-preset", "speckit.specify",+ "Legacy skills test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Simulate a registry entry written by a pre-#2948 spec-kit version:+ # registered_skills stored as a flat list with no per-agent+ # provenance, rather than the dict shape install_from_directory+ # writes today.+ manager.registry.update(+ "legacy-skills-preset", {"registered_skills": ["speckit-specify"]},+ )+ metadata = manager.registry.get("legacy-skills-preset")+ assert isinstance(metadata["registered_skills"], list), (+ "sanity: the injected legacy format is a flat list"+ )++ # Rescaffold for the *same* active agent (claude) with no actual+ # change to the registered skill names, mirroring `integration+ # upgrade claude` re-running registration for the active+ # integration.+ manager.register_enabled_presets_for_agent("claude")++ metadata = manager.registry.get("legacy-skills-preset")+ registered_skills = metadata.get("registered_skills")+ assert isinstance(registered_skills, dict), (+ "rescaffold must migrate a legacy flat-list registered_skills "+ "entry to the per-agent dict format even when the "+ "rescaffolded names are unchanged, or the raw registry stays "+ "un-migrated and later removal loses per-agent provenance "+ "(#2948)"+ )+ assert registered_skills.get("claude") == ["speckit-specify"]++ # Switch to a different skill-mode agent and rescaffold again β+ # with the dict format now in place, both directories should be+ # tracked and therefore restorable on removal.+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")++ metadata = manager.registry.get("legacy-skills-preset")+ assert set(metadata.get("registered_skills", {})) == {"claude", "codex"}, (+ "the migrated dict must keep recording every agent directory "+ "the preset actually wrote to, exactly like a preset that was "+ "always in dict format (#2948)"+ )++ assert manager.remove("legacy-skills-preset") is True++ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"+ for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):+ assert skill_file.exists(), f"{label} skill file should still exist after removal"+ content = skill_file.read_text()+ assert "preset:legacy-skills-preset" not in content, (+ f"{label}'s preset override must be restored on removal, "+ "not orphaned because the registry stayed in legacy "+ "flat-list format (#2948)"+ )+ assert "Core specify body" in content++ def test_rescaffold_legacy_flat_list_direct_switch_preserves_original_agent(+ self, project_dir, temp_dir+ ):+ """A legacy flat-list ``registered_skills`` entry must not be+ misattributed to the wrong agent when the *first* post-upgrade+ operation is a direct switch to a different skill-mode agent.++ Blindly attributing every legacy flat-list name to ``agent_name`` β+ the agent currently being (re)activated β loses the actual writer+ whenever that first operation is ``integration use codex`` (or+ ``switch``) run directly against a legacy Claude override, without+ an intervening same-agent rescaffold for Claude first. The+ migrated dict then only records ``{"codex": [...]}``, so a later+ ``remove()`` restores Codex but permanently orphans the Claude+ override that was never in the registry to begin with (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "legacy-direct-switch-preset", "speckit.specify",+ "Legacy direct switch test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # install_from_directory wrote the preset's override to Claude's+ # skill directory (the active agent at install time) β sanity-check+ # that the marker is actually there before simulating the legacy+ # registry format.+ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:legacy-direct-switch-preset" in claude_skill.read_text(), (+ "sanity: install should have written the override under claude"+ )++ # Simulate a pre-#2948 registry: a flat list with no per-agent+ # provenance, even though the file on disk was actually written+ # under claude's directory.+ manager.registry.update(+ "legacy-direct-switch-preset",+ {"registered_skills": ["speckit-specify"]},+ )++ # Directly switch to codex β no intervening rescaffold for claude β+ # mirroring `integration use codex` / `switch codex` run right after+ # upgrading spec-kit versions.+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")++ metadata = manager.registry.get("legacy-direct-switch-preset")+ registered_skills = metadata.get("registered_skills")+ assert isinstance(registered_skills, dict)+ assert set(registered_skills) == {"claude", "codex"}, (+ "migrating a legacy flat-list entry on a direct switch must "+ "infer the actual writer (claude) from the existing on-disk "+ "SKILL.md provenance, not attribute every name to whichever "+ "agent happens to be activated first after the upgrade "+ "(#2948)"+ )++ assert manager.remove("legacy-direct-switch-preset") is True++ codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"+ for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):+ assert skill_file.exists(), f"{label} skill file should still exist after removal"+ content = skill_file.read_text()+ assert "preset:legacy-direct-switch-preset" not in content, (+ f"{label}'s preset override must be restored on removal, "+ "not permanently orphaned by a misattributed legacy "+ "migration (#2948)"+ )+ assert "Core specify body" in content++ def test_rescaffold_legacy_flat_list_infers_command_backed_skills_owner(+ self, project_dir, temp_dir+ ):+ """Legacy provenance inference must also probe command-backed agents+ that were running in skills mode, not only agents whose command+ registrar config is statically ``/SKILL.md``-only.++ Copilot is command-backed (``extension: ".agent.md"``), but with+ ``ai_skills`` enabled its preset overrides render as ``SKILL.md``+ files under ``.github/skills`` exactly like a native skill-only+ agent (claude, codex, ...). Before the fix,+ ``_infer_legacy_skill_provenance`` only probed agents whose+ registrar config has a static ``extension == "/SKILL.md"``, so a+ real preset-owned ``.github/skills/.../SKILL.md`` written while+ Copilot was the active, skills-mode agent was never found β the+ legacy flat list was misattributed entirely to whichever agent the+ first post-upgrade switch happened to activate, permanently+ orphaning Copilot's override on later removal (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ copilot_skills_dir = project_dir / ".github" / "skills"+ self._create_skill(copilot_skills_dir, "speckit-specify")+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "legacy-copilot-skills-preset", "speckit.specify",+ "Legacy copilot skills test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ copilot_skill = copilot_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:legacy-copilot-skills-preset" in copilot_skill.read_text(), (+ "sanity: install should have written the override under "+ "copilot's skills directory while copilot was active in "+ "skills mode"+ )+ # Sanity: no command-mode artifact was written either β copilot's+ # command file and skills file are mutually exclusive.+ assert not list((project_dir / ".github" / "agents").glob("*specify*")), (+ "sanity: copilot in skills mode must not also write a command "+ "file that could be falsely attributed instead"+ )++ # Simulate a pre-#2948 registry: a flat list with no per-agent+ # provenance, even though the file on disk was actually written+ # under copilot's skills directory.+ manager.registry.update(+ "legacy-copilot-skills-preset",+ {"registered_skills": ["speckit-specify"]},+ )++ # Directly switch to claude β no intervening rescaffold for+ # copilot β mirroring `integration use claude` run right after+ # upgrading spec-kit versions.+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ manager.register_enabled_presets_for_agent("claude")++ metadata = manager.registry.get("legacy-copilot-skills-preset")+ registered_skills = metadata.get("registered_skills")+ assert isinstance(registered_skills, dict)+ assert set(registered_skills) == {"copilot", "claude"}, (+ "migrating a legacy flat-list entry on a direct switch must "+ "infer the actual writer (copilot, running in skills mode) "+ "even though copilot's registrar config is command-backed, "+ "not just agents with a static /SKILL.md extension (#2948)"+ )++ assert manager.remove("legacy-copilot-skills-preset") is True++ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ for skill_file, label in ((copilot_skill, "copilot"), (claude_skill, "claude")):+ assert skill_file.exists(), f"{label} skill file should still exist after removal"+ content = skill_file.read_text()+ assert "preset:legacy-copilot-skills-preset" not in content, (+ f"{label}'s preset override must be restored on removal, "+ "not permanently orphaned by a legacy migration that "+ "failed to probe command-backed skills-mode agents (#2948)"+ )+ assert "Core specify body" in content++ def test_composed_none_unregister_respects_active_agent(+ self, project_dir, temp_dir+ ):+ """Unregistering a stale composed command must only touch the+ active agent's directory, not every configured non-skill agent.++ When a wrap preset's base layer is removed, ``resolve_content`` can+ no longer find a replace layer to compose onto and returns+ ``None``, triggering the "composed is None" branch of+ ``_reconcile_composed_commands``. Before the fix, that+ unregistration mapping covered every configured non-skill agent+ regardless of ``only_agent``, deleting historical artifacts from+ integrations that were never active for this preset (#2948).+ """+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_commands_dir = project_dir / ".gemini" / "commands"+ gemini_commands_dir.mkdir(parents=True)++ # A made-up command name with no bundled/core equivalent, so the+ # *only* base layer is the "compose-base" preset installed below β+ # once it's removed, no base remains for the wrap preset to compose+ # onto.+ cmd_name = "speckit.fake-compose-test"+ base_dir = self._create_command_preset(+ temp_dir, "compose-base", cmd_name, "Base", "base body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(base_dir, "0.1.5", priority=10)++ wrap_dir = temp_dir / "compose-wrap"+ wrap_dir.mkdir()+ (wrap_dir / "commands").mkdir()+ (wrap_dir / "commands" / f"{cmd_name}.md").write_text(+ "---\ndescription: Wrap\nstrategy: wrap\n---\n\n"+ "wrap start\n{CORE_TEMPLATE}\nwrap end\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "compose-wrap",+ "name": "compose-wrap",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": cmd_name,+ "file": f"commands/{cmd_name}.md",+ "strategy": "wrap",+ }+ ]+ },+ }+ with open(wrap_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)+ manager.install_from_directory(wrap_dir, "0.1.5", priority=5)++ cmd_file = gemini_commands_dir / f"{cmd_name}.toml"+ assert cmd_file.exists(), (+ "sanity: the composed command should register for the active agent"+ )++ # Simulate a pre-existing artifact for an inactive agent, predating+ # this preset entirely β active-only unregistration must never+ # touch it.+ opencode_dir = project_dir / ".opencode" / "commands"+ opencode_dir.mkdir(parents=True, exist_ok=True)+ opencode_stale_file = opencode_dir / f"{cmd_name}.md"+ opencode_stale_file.write_text("stale opencode content\n")++ assert manager.remove("compose-base") is True++ assert not cmd_file.exists(), (+ "sanity: the active agent's now-uncomposable command file must "+ "be unregistered"+ )+ assert opencode_stale_file.read_text() == "stale opencode content\n", (+ "unregistering a stale composed command must not touch an "+ "inactive agent's directory (#2948)"+ )++ def test_remove_reconciles_command_for_every_historical_agent(+ self, project_dir, temp_dir+ ):+ """Removing a preset must reconcile every historical agent its+ ``registered_commands`` actually targeted, not only the currently+ active one.++ Preset B (lower precedence, survives) is installed while gemini is+ active, then preset A (higher precedence) overrides the same+ command while gemini is still active. Switching the active+ integration to opencode and rescaffolding re-registers both+ presets under opencode too, so preset A's ``registered_commands``+ now spans two agents: gemini (now inactive) and opencode (active).+ Removing A deletes its command file from *both* directories via+ ``_unregister_commands``, but active-only reconciliation used to+ recreate the surviving preset B's content only for the active+ agent (opencode), leaving gemini's directory with a stale/missing+ file (#2948).+ """+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ preset_b_dir = self._create_command_preset(+ temp_dir, "hist-preset-b", "speckit.specify",+ "Preset B", "preset B body",+ )+ preset_a_dir = self._create_command_preset(+ temp_dir, "hist-preset-a", "speckit.specify",+ "Preset A", "preset A body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)+ manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)++ gemini_cmd_files = list(gemini_dir.glob("*specify*"))+ assert gemini_cmd_files, "sanity: gemini should have the command file"+ assert "preset A body" in gemini_cmd_files[0].read_text(), (+ "sanity: preset A (higher precedence) should win initially"+ )++ # Switch the active integration to opencode and rescaffold, mirroring+ # `integration use opencode`. This merges opencode into both+ # presets' registered_commands alongside the pre-existing gemini+ # entry recorded while gemini was active.+ self._write_init_options(project_dir, ai="opencode", ai_skills=False)+ opencode_dir = project_dir / ".opencode" / "commands"+ opencode_dir.mkdir(parents=True, exist_ok=True)+ manager.register_enabled_presets_for_agent("opencode")++ metadata_a = manager.registry.get("hist-preset-a")+ assert set(metadata_a.get("registered_commands", {})) == {"gemini", "opencode"}, (+ "sanity: preset A's registered_commands must span both the "+ "historical (gemini) and currently active (opencode) agents"+ )++ assert manager.remove("hist-preset-a") is True++ gemini_cmd_files = list(gemini_dir.glob("*specify*"))+ opencode_cmd_files = list(opencode_dir.glob("*specify*"))+ assert gemini_cmd_files, "gemini's command file must still exist after removal"+ assert opencode_cmd_files, "opencode's command file must still exist after removal"+ assert "preset B body" in gemini_cmd_files[0].read_text(), (+ "removing the higher-precedence preset must restore the "+ "surviving preset's content in the historical (inactive) "+ "agent's directory too, not only the active agent's (#2948)"+ )+ assert "preset B body" in opencode_cmd_files[0].read_text(), (+ "the surviving preset's content must also be restored for the "+ "currently active agent"+ )++ def test_remove_reconciliation_tracks_new_historical_agent_for_survivor(+ self, project_dir, temp_dir+ ):+ """Historical-agent reconciliation writes must be recorded in the+ surviving preset's own ``registered_commands``, not just written+ to disk and forgotten.++ Preset A is installed while gemini is active, then survives to be+ active under opencode too (so A's ``registered_commands`` spans+ both gemini and opencode). Preset B is installed *only* while+ opencode is active β B's ``registered_commands`` is+ ``{"opencode": [...]}`` and never mentions gemini. Removing A+ triggers reconciliation that writes B's content into gemini's+ directory (an agent B never wrote to before) via ``extra_agents``,+ but if that write isn't merged back into B's own+ ``registered_commands``, B's registry entry still only says+ ``{"opencode": [...]}`` even though B's content now lives in+ gemini's directory too. A later ``remove('b')`` then only cleans+ up opencode, leaving the gemini file β reconciled there entirely+ by side effect of removing A β as a permanent orphan with no+ preset tracking it (#2948).+ """+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ preset_a_dir = self._create_command_preset(+ temp_dir, "orphan-preset-a", "speckit.specify",+ "Preset A", "preset A body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)++ self._write_init_options(project_dir, ai="opencode", ai_skills=False)+ opencode_dir = project_dir / ".opencode" / "commands"+ opencode_dir.mkdir(parents=True, exist_ok=True)+ manager.register_enabled_presets_for_agent("opencode")++ metadata_a = manager.registry.get("orphan-preset-a")+ assert set(metadata_a.get("registered_commands", {})) == {"gemini", "opencode"}, (+ "sanity: preset A must be tracked under both agents"+ )++ # Preset B is installed only now, while opencode is the sole+ # active agent β it never writes to or tracks gemini.+ preset_b_dir = self._create_command_preset(+ temp_dir, "orphan-preset-b", "speckit.specify",+ "Preset B", "preset B body",+ )+ manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)++ metadata_b = manager.registry.get("orphan-preset-b")+ assert set(metadata_b.get("registered_commands", {})) == {"opencode"}, (+ "sanity: preset B must only be tracked for opencode before "+ "preset A is removed"+ )++ assert manager.remove("orphan-preset-a") is True++ # B is now written into gemini's directory as a side effect of+ # reconciling A's removal, via the historical-agent extra_agents+ # pass.+ gemini_cmd_files = list(gemini_dir.glob("*specify*"))+ assert gemini_cmd_files, "sanity: gemini's directory must have B's restored content"+ assert "preset B body" in gemini_cmd_files[0].read_text(encoding="utf-8")++ metadata_b = manager.registry.get("orphan-preset-b")+ assert set(metadata_b.get("registered_commands", {})) == {"gemini", "opencode"}, (+ "preset B's own registered_commands must be updated to "+ "include gemini once reconciliation actually writes content "+ "there on its behalf β otherwise B's registry entry silently "+ "lies about which directories it owns (#2948)"+ )++ assert manager.remove("orphan-preset-b") is True++ # No preset is installed any more, so gemini's file must have been+ # reconciled down to the core bundled template (or removed+ # entirely) β but it must NOT still contain B's stale content,+ # which would mean B's write there was never tracked for cleanup.+ remaining_gemini_files = list(gemini_dir.glob("*specify*"))+ for f in remaining_gemini_files:+ assert "preset B body" not in f.read_text(encoding="utf-8"), (+ "removing preset B must clean up gemini's directory too, "+ "since B's registered_commands was updated to include it "+ "β otherwise B's stale content is orphaned there forever "+ "with no preset left to track or clean it up (#2948)"+ )++ def test_extension_reconciliation_tracks_new_historical_agent(+ self, project_dir+ ):+ from specify_cli.extensions import ExtensionRegistry++ self._write_init_options(project_dir, ai="opencode", ai_skills=False)+ (project_dir / ".opencode" / "commands").mkdir(parents=True)+ (project_dir / ".gemini" / "commands").mkdir(parents=True)++ ext_dir = project_dir / ".specify" / "extensions" / "tracked-ext"+ (ext_dir / "commands").mkdir(parents=True)+ (ext_dir / "commands" / "tracked.md").write_text(+ "---\ndescription: tracked\n---\n\nExtension body\n",+ encoding="utf-8",+ )+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: tracked-ext\n name: Tracked\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " commands:\n"+ " - name: speckit.tracked\n"+ " file: commands/tracked.md\n"+ " description: Tracked command\n",+ encoding="utf-8",+ )+ ExtensionRegistry(ext_dir.parent).add(+ "tracked-ext",+ {+ "version": "1.0.0",+ "source": "dev",+ "enabled": True,+ "registered_commands": {+ "opencode": ["speckit.tracked-ext.tracked"]+ },+ },+ )++ manager = PresetManager(project_dir)+ manager._reconcile_composed_commands(+ ["speckit.tracked-ext.tracked"], extra_agents={"gemini"}+ )++ assert list((project_dir / ".gemini" / "commands").glob("*tracked*"))+ metadata = ExtensionRegistry(ext_dir.parent).get("tracked-ext")+ assert set(metadata["registered_commands"]) == {"gemini", "opencode"}++ def test_copilot_skills_registration_restored_after_process_restart(+ self, project_dir, temp_dir+ ):+ """Copilot skills-mode registrations must restore even when the+ transient ``_skills_mode`` integration attribute has been reset,+ simulating a fresh CLI process.++ ``_skills_mode`` is set during ``setup()`` and is never persisted;+ after switching the active agent and running ``preset remove`` in+ a brand-new process, a naive "is this integration currently in+ skills mode" check would be False even though Copilot's+ ``.github/skills`` directory holds a live override this preset+ wrote. Restoration must rely on the persisted per-agent provenance+ recorded at write time, not on runtime integration state (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )+ copilot_skills_dir = project_dir / ".github" / "skills"+ self._create_skill(copilot_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "copilot-fresh-process-preset", "speckit.specify",+ "Copilot fresh process test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = copilot_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:copilot-fresh-process-preset" in skill_file.read_text()++ metadata = manager.registry.get("copilot-fresh-process-preset")+ assert "copilot" in metadata.get("registered_skills", {})++ # Switch the active agent away from copilot, then simulate a fresh+ # CLI process (a brand-new PresetManager, so any transient+ # `_skills_mode` state set during a prior setup() call is gone)+ # removing the preset.+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ fresh_manager = PresetManager(project_dir)++ assert fresh_manager.remove("copilot-fresh-process-preset") is True++ assert "preset:copilot-fresh-process-preset" not in skill_file.read_text(), (+ "removal must restore copilot's .github/skills override even "+ "when copilot's transient skills-mode state isn't set in this "+ "process (#2948)"+ )+ assert "Core specify body" in skill_file.read_text()++ def test_unregister_agent_artifacts_scoped_to_target_agent_only(+ self, project_dir, temp_dir+ ):+ """``unregister_agent_artifacts`` must remove only the target+ agent's own tracked command/skill artifacts.++ Used by ``integration switch`` when deactivating the previous+ integration for a not-yet-installed target (#2948): without this,+ a preset's command override -- including a custom preset command --+ and skill mirror rendered for the old agent remain orphaned once a+ different integration becomes active. Another agent's own+ registrations (files and registry tracking) must survive+ untouched, and no priority-stack reconciliation should run as a+ side effect.+ """+ self._write_init_options(project_dir, ai="auggie", ai_skills=False)+ # Registration only writes to an agent's directory once it's+ # "detected" on disk (mirroring a real `integration install`+ # having already created it), so pre-create both agents'+ # directories before installing the preset.+ (project_dir / ".augment" / "commands").mkdir(parents=True)+ (project_dir / ".opencode" / "commands").mkdir(parents=True)+ preset_dir = self._create_command_preset(+ temp_dir, "switch-cleanup-preset", "speckit.specify",+ "Custom preset command", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ auggie_cmd = project_dir / ".augment" / "commands" / "speckit.specify.md"+ assert auggie_cmd.exists(), "sanity: preset command registered for auggie"++ # Simulate a later `integration use opencode` rescaffold that also+ # registered the preset for opencode, while auggie's own+ # registration (from before the switch) is still present in the+ # registry.+ self._write_init_options(project_dir, ai="opencode", ai_skills=False)+ manager.register_enabled_presets_for_agent("opencode")++ opencode_cmd = project_dir / ".opencode" / "commands" / "speckit.specify.md"+ assert opencode_cmd.exists(), "sanity: preset command registered for opencode"++ metadata = manager.registry.get("switch-cleanup-preset")+ registered_commands = metadata.get("registered_commands", {})+ assert "auggie" in registered_commands and "opencode" in registered_commands++ manager.unregister_agent_artifacts("auggie")++ assert not auggie_cmd.exists(), (+ "auggie's own preset command must be removed when switching "+ "away from auggie to a not-yet-installed integration (#2948)"+ )+ assert opencode_cmd.exists(), (+ "opencode's preset command must survive unregistering auggie's "+ "artifacts -- cleanup must stay scoped to the target agent"+ )++ metadata = manager.registry.get("switch-cleanup-preset")+ registered_commands = metadata.get("registered_commands", {})+ assert "auggie" not in registered_commands, (+ "auggie's tracking must be dropped after unregistering its artifacts"+ )+ assert "opencode" in registered_commands, (+ "opencode's tracking must be preserved untouched"+ )++ def test_unregister_agent_artifacts_deletes_marker_owned_skill(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")+ preset_dir = self._create_command_preset(+ temp_dir,+ "deactivated-skill-preset",+ "speckit.specify",+ "Deactivation cleanup",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_dir = skills_dir / "speckit-specify"+ assert "preset:deactivated-skill-preset" in (+ skill_dir / "SKILL.md"+ ).read_text()++ manager.unregister_agent_artifacts("copilot")++ assert not skill_dir.exists()++ def test_unregister_agent_artifacts_deletes_reconciled_override_skill(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skills_dir = project_dir / ".github" / "skills"+ self._create_skill(skills_dir, "speckit-specify")+ preset_dir = self._create_command_preset(+ temp_dir,+ "deactivated-override-preset",+ "speckit.specify",+ "Deactivation override cleanup",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Project override\n---\n\nOverride body\n",+ encoding="utf-8",+ )+ (+ manager.presets_dir+ / "deactivated-override-preset"+ / "commands"+ / "speckit.specify.md"+ ).unlink()+ manager.register_enabled_presets_for_agent("copilot")++ skill_dir = skills_dir / "speckit-specify"+ assert "override:speckit.specify" in (+ skill_dir / "SKILL.md"+ ).read_text(encoding="utf-8")++ manager.unregister_agent_artifacts("copilot")++ assert not skill_dir.exists()+ metadata = manager.registry.get("deactivated-override-preset")+ assert "copilot" not in metadata.get("registered_skills", {})++ def test_unregister_native_agent_persists_skills_metadata_pop(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="agy", ai_skills=True)+ (project_dir / ".agents" / "skills").mkdir(parents=True)+ preset_dir = self._create_command_preset(+ temp_dir,+ "native-metadata-cleanup-preset",+ "speckit.shared-cleanup",+ "Shared cleanup",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ metadata = manager.registry.get("native-metadata-cleanup-preset")+ assert "agy" in metadata.get("registered_commands", {})+ manager.registry.update(+ "native-metadata-cleanup-preset",+ {"registered_skills": {"agy": ["speckit-shared-cleanup"]}},+ )++ manager.unregister_agent_artifacts("agy")++ metadata = manager.registry.get("native-metadata-cleanup-preset")+ assert "agy" not in metadata.get("registered_commands", {})+ assert "agy" not in metadata.get("registered_skills", {})++ def test_unregister_native_agent_preserves_shared_output_owner(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="agy", ai_skills=True)+ (project_dir / ".agents" / "skills").mkdir(parents=True)+ preset_dir = self._create_command_preset(+ temp_dir,+ "shared-native-output-preset",+ "speckit.shared-owner",+ "Shared owner",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")+ skill_file = (+ project_dir+ / ".agents"+ / "skills"+ / "speckit-shared-owner"+ / "SKILL.md"+ )+ assert skill_file.exists()+ metadata = manager.registry.get("shared-native-output-preset")+ registered_commands = metadata.get("registered_commands", {})+ assert "agy" in registered_commands and "codex" in registered_commands++ manager.unregister_agent_artifacts("agy")++ assert skill_file.exists(), (+ "shared SKILL.md must survive while codex still owns the same "+ "physical output"+ )+ metadata = manager.registry.get("shared-native-output-preset")+ registered_commands = metadata.get("registered_commands", {})+ assert "agy" not in registered_commands+ assert "codex" in registered_commands++ def test_unregister_agent_artifacts_migrates_legacy_skill_list_scoped(+ self, project_dir, temp_dir+ ):+ """Unregistering an agent's artifacts from a legacy flat-list+ ``registered_skills`` entry must infer real per-agent ownership+ before removing anything, so only the target agent's own share is+ cleaned up and any other agent's still-live mirror survives,+ rather than either guessing every name belongs to the target agent+ or dropping all tracking wholesale (#2948).++ Uses Copilot (command-backed, rendering skills via ``ai_skills``)+ as the agent being switched away from, and Claude (a native+ SKILL.md agent) as the separate, still-live owner β mirroring the+ established legacy-provenance test pattern used elsewhere for+ this exact registry shape.+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ copilot_skills_dir = project_dir / ".github" / "skills"+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(copilot_skills_dir, "speckit-specify")+ self._create_skill(claude_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "switch-legacy-skill-preset", "speckit.specify",+ "Legacy skill switch test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ copilot_skill = copilot_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:switch-legacy-skill-preset" in copilot_skill.read_text(), (+ "sanity: install wrote the override under copilot"+ )++ # A separate activation under claude (before provenance tracking+ # existed) also left a live, marker-verified mirror there.+ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ claude_skill.write_text(+ "---\nname: speckit-specify\nmetadata:\n source: preset:switch-legacy-skill-preset\n"+ "---\n\npreset body\n",+ encoding="utf-8",+ )++ # Simulate a pre-#2948 registry: a flat list with no per-agent+ # provenance for either writer.+ manager.registry.update(+ "switch-legacy-skill-preset",+ {"registered_skills": ["speckit-specify"]},+ )++ manager.unregister_agent_artifacts("copilot")++ assert not copilot_skill.parent.exists(), (+ "copilot's marker-owned preset skill must be deleted when "+ "switching away from copilot"+ )++ assert "preset:switch-legacy-skill-preset" in claude_skill.read_text(), (+ "claude's own, separately-written mirror must survive "+ "unregistering copilot's artifacts -- legacy-list inference "+ "must not misattribute or drop claude's real ownership (#2948)"+ )++ metadata = manager.registry.get("switch-legacy-skill-preset")+ registered_skills = metadata.get("registered_skills")+ assert isinstance(registered_skills, dict), (+ "legacy flat-list value must migrate to per-agent form"+ )+ assert "copilot" not in registered_skills+ assert "claude" in registered_skills and "speckit-specify" in registered_skills["claude"], (+ "claude's real ownership must be preserved in the migrated tracking"+ )++ def test_short_and_namespaced_commands_scaffold_consistently(+ self, project_dir, temp_dir+ ):+ """A preset's ``speckit.<cmd>`` and ``speckit.<ns>.<cmd>`` commands must+ scaffold identically in command mode, with no installed extension.++ Regression: the 3-part (``speckit.<ns>.<cmd>``) form was silently+ dropped by a name-shape guard whenever ``.specify/extensions/<ns>/``+ was absent, even though the preset ships the command body itself. The+ 2-part form always scaffolded. Both are self-contained and must behave+ the same (#4076).+ """+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_commands_dir = project_dir / ".gemini" / "commands"+ gemini_commands_dir.mkdir(parents=True)++ short_preset = self._create_command_preset(+ temp_dir, "short-cmd", "speckit.newcmd", "Short", "short body",+ )+ ns_preset = self._create_command_preset(+ temp_dir, "ns-cmd", "speckit.fakeext.newcmd", "Namespaced", "ns body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(short_preset, "0.1.5")+ manager.install_from_directory(ns_preset, "0.1.5")++ short_file = gemini_commands_dir / "speckit.newcmd.toml"+ ns_file = gemini_commands_dir / "speckit.fakeext.newcmd.toml"+ assert short_file.exists(), "2-part command should scaffold"+ assert ns_file.exists(), (+ "3-part namespaced command must scaffold too, even without the "+ "matching extension installed"+ )+ assert manager.registry.get("short-cmd")["registered_commands"] != {}+ assert manager.registry.get("ns-cmd")["registered_commands"] != {}+++class TestWrapStrategy:+ """Tests for strategy: wrap preset command substitution."""++ def test_substitute_core_template_replaces_placeholder(self, project_dir):+ """Core template body replaces {CORE_TEMPLATE} in preset command body."""+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ # Set up a core command template+ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\n---\n\n# Core Specify\n\nDo the thing.\n"+ )++ registrar = CommandRegistrar()+ body = "## Pre-Logic\n\nBefore stuff.\n\n{CORE_TEMPLATE}\n\n## Post-Logic\n\nAfter stuff.\n"+ result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)++ assert "{CORE_TEMPLATE}" not in result+ assert "# Core Specify" in result+ assert "## Pre-Logic" in result+ assert "## Post-Logic" in result+ assert core_fm.get("description") == "core"++ def test_substitute_core_template_no_op_when_placeholder_absent(self, project_dir):+ """Returns body unchanged when {CORE_TEMPLATE} is not present."""+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCore body.\n")++ registrar = CommandRegistrar()+ body = "## No placeholder here.\n"+ result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)+ assert result == body+ assert core_fm == {}++ def test_substitute_core_template_no_op_when_core_missing(self, project_dir):+ """Returns body unchanged when core template file does not exist."""+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ registrar = CommandRegistrar()+ body = "Pre.\n\n{CORE_TEMPLATE}\n\nPost.\n"+ result, core_fm = _substitute_core_template(body, "nonexistent", project_dir, registrar)+ assert result == body+ assert "{CORE_TEMPLATE}" in result+ assert core_fm == {}++ def test_substitute_core_template_unreadable_core_treated_as_missing(+ self, project_dir+ ):+ """An undecodable core template must not crash substitution.++ The wrap-strategy callers (``CommandRegistrar.register_pack`` and+ ``_register_commands``) skip an unreadable preset source with a+ warning, but the core template read inside+ ``_substitute_core_template`` had no boundary, so one corrupted+ project-owned override in ``.specify/templates/commands/`` crashed+ the whole registration with a raw ``UnicodeDecodeError``. An+ unreadable core is treated like a missing one.+ """+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_bytes(b"\xff\xfe not utf-8")++ registrar = CommandRegistrar()+ body = "Pre.\n\n{CORE_TEMPLATE}\n\nPost.\n"+ with pytest.warns(UserWarning, match="Ignoring core template"):+ result, core_fm = _substitute_core_template(+ body, "specify", project_dir, registrar+ )+ assert result == body+ assert core_fm == {}++ def test_register_commands_substitutes_core_template_for_wrap_strategy(self, project_dir):+ """register_commands substitutes {CORE_TEMPLATE} when strategy: wrap."""+ from specify_cli.agents import CommandRegistrar++ # Set up core command template+ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\n---\n\n# Core Specify\n\nCore body here.\n"+ )++ # Create a preset command dir with a wrap-strategy command+ cmd_dir = project_dir / "preset" / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)+ (cmd_dir / "speckit.specify.md").write_text(+ "---\ndescription: wrap test\nstrategy: wrap\n---\n\n"+ "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"+ )++ commands = [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}]+ registrar = CommandRegistrar()++ # Use a generic agent that writes markdown to commands/+ agent_dir = project_dir / ".claude" / "commands"+ agent_dir.mkdir(parents=True, exist_ok=True)++ # Patch AGENT_CONFIGS to use a simple markdown agent pointing at our dir+ import copy+ original = copy.deepcopy(registrar.AGENT_CONFIGS)+ registrar.AGENT_CONFIGS["test-agent"] = {+ "dir": str(agent_dir.relative_to(project_dir)),+ "format": "markdown",+ "args": "$ARGUMENTS",+ "extension": ".md",+ "strip_frontmatter_keys": [],+ }+ try:+ registrar.register_commands(+ "test-agent", commands, "test-preset",+ project_dir / "preset", project_dir+ )+ finally:+ CommandRegistrar.AGENT_CONFIGS.clear()+ CommandRegistrar.AGENT_CONFIGS.update(original)++ written = (agent_dir / "speckit.specify.md").read_text()+ assert "{CORE_TEMPLATE}" not in written+ assert "# Core Specify" in written+ assert "## Pre" in written+ assert "## Post" in written++ def test_end_to_end_wrap_via_self_test_preset(self, project_dir):+ """Installing self-test preset with a wrap command substitutes {CORE_TEMPLATE}."""+ from specify_cli.presets import PresetManager++ # Install a core template that wrap-test will wrap around+ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "wrap-test.md").write_text(+ "---\ndescription: core wrap-test\n---\n\n# Core Wrap-Test Body\n"+ )++ # Set up skills dir (simulating --integration claude)+ skills_dir = project_dir / ".claude" / "skills"+ skills_dir.mkdir(parents=True, exist_ok=True)+ skill_subdir = skills_dir / "speckit-wrap-test"+ skill_subdir.mkdir()+ (skill_subdir / "SKILL.md").write_text("---\nname: speckit-wrap-test\n---\n\nold content\n")++ # Write init-options so _register_skills finds the claude skills dir+ import json+ (project_dir / ".specify" / "init-options.json").write_text(+ json.dumps({"ai": "claude", "ai_skills": True})+ )++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ written = (skill_subdir / "SKILL.md").read_text()+ assert "{CORE_TEMPLATE}" not in written+ assert "# Core Wrap-Test Body" in written+ assert "preset:self-test wrap-pre" in written+ assert "preset:self-test wrap-post" in written++ def test_substitute_core_template_returns_core_scripts(self, project_dir):+ """core_frontmatter in the returned tuple includes scripts/agent_scripts."""+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: run.sh\nagent_scripts:\n sh: agent-run.sh\n---\n\n# Body\n"+ )++ registrar = CommandRegistrar()+ body = "## Wrapper\n\n{CORE_TEMPLATE}\n"+ result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)++ assert "# Body" in result+ assert core_fm.get("scripts") == {"sh": "run.sh"}+ assert core_fm.get("agent_scripts") == {"sh": "agent-run.sh"}++ def test_register_commands_inherits_scripts_from_core(self, project_dir):+ """register_commands merges scripts/agent_scripts from core and normalizes paths."""+ from specify_cli.agents import CommandRegistrar+ import copy++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"+ "Run: {SCRIPT}\n"+ )++ cmd_dir = project_dir / "preset" / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)+ # Preset has strategy: wrap but no scripts of its own+ (cmd_dir / "speckit.specify.md").write_text(+ "---\ndescription: wrap no scripts\nstrategy: wrap\n---\n\n"+ "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"+ )++ agent_dir = project_dir / ".claude" / "commands"+ agent_dir.mkdir(parents=True, exist_ok=True)++ registrar = CommandRegistrar()+ original = copy.deepcopy(registrar.AGENT_CONFIGS)+ registrar.AGENT_CONFIGS["test-agent"] = {+ "dir": str(agent_dir.relative_to(project_dir)),+ "format": "markdown",+ "args": "$ARGUMENTS",+ "extension": ".md",+ "strip_frontmatter_keys": [],+ }+ try:+ registrar.register_commands(+ "test-agent",+ [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],+ "test-preset",+ project_dir / "preset",+ project_dir,+ )+ finally:+ CommandRegistrar.AGENT_CONFIGS.clear()+ CommandRegistrar.AGENT_CONFIGS.update(original)++ written = (agent_dir / "speckit.specify.md").read_text()+ assert "{CORE_TEMPLATE}" not in written+ assert "Run:" in written+ assert "scripts:" in written+ assert "run.sh" in written++ def test_register_commands_toml_resolves_inherited_scripts(self, project_dir):+ """TOML agents resolve {SCRIPT} from inherited core scripts when preset omits them."""+ from specify_cli.agents import CommandRegistrar+ import copy++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"+ "Run: {SCRIPT}\n"+ )++ cmd_dir = project_dir / "preset" / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)+ (cmd_dir / "speckit.specify.md").write_text(+ "---\ndescription: toml wrap\nstrategy: wrap\n---\n\n"+ "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"+ )++ toml_dir = project_dir / ".gemini" / "commands"+ toml_dir.mkdir(parents=True, exist_ok=True)++ registrar = CommandRegistrar()+ original = copy.deepcopy(registrar.AGENT_CONFIGS)+ registrar.AGENT_CONFIGS["test-toml-agent"] = {+ "dir": str(toml_dir.relative_to(project_dir)),+ "format": "toml",+ "args": "{{args}}",+ "extension": ".toml",+ "strip_frontmatter_keys": [],+ }+ try:+ registrar.register_commands(+ "test-toml-agent",+ [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],+ "test-preset",+ project_dir / "preset",+ project_dir,+ )+ finally:+ CommandRegistrar.AGENT_CONFIGS.clear()+ CommandRegistrar.AGENT_CONFIGS.update(original)++ written = (toml_dir / "speckit.specify.toml").read_text()+ assert "{CORE_TEMPLATE}" not in written+ assert "{SCRIPT}" not in written+ assert "run.sh" in written+ # args token must use TOML format, not the intermediate $ARGUMENTS+ assert "$ARGUMENTS" not in written+ assert "{{args}}" in written++ def test_register_commands_markdown_resolves_inherited_scripts(self, project_dir):+ """Markdown agents resolve {SCRIPT} from inherited core scripts when preset omits them."""+ from specify_cli.agents import CommandRegistrar+ import copy++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"+ "Run: {SCRIPT}\n"+ )++ cmd_dir = project_dir / "preset" / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)+ (cmd_dir / "speckit.specify.md").write_text(+ "---\ndescription: markdown wrap\nstrategy: wrap\n---\n\n"+ "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"+ )++ agent_dir = project_dir / ".claude" / "commands"+ agent_dir.mkdir(parents=True, exist_ok=True)++ registrar = CommandRegistrar()+ original = copy.deepcopy(registrar.AGENT_CONFIGS)+ registrar.AGENT_CONFIGS["test-md-agent"] = {+ "dir": str(agent_dir.relative_to(project_dir)),+ "format": "markdown",+ "args": "$ARGUMENTS",+ "extension": ".md",+ "strip_frontmatter_keys": [],+ }+ try:+ registrar.register_commands(+ "test-md-agent",+ [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],+ "test-preset",+ project_dir / "preset",+ project_dir,+ )+ finally:+ CommandRegistrar.AGENT_CONFIGS.clear()+ CommandRegistrar.AGENT_CONFIGS.update(original)++ written = (agent_dir / "speckit.specify.md").read_text()+ assert "{CORE_TEMPLATE}" not in written+ assert "{SCRIPT}" not in written+ assert "run.sh" in written+ assert "strategy" not in written++ def test_register_commands_markdown_converts_args_after_script_resolution(self, project_dir):+ """Markdown agents re-run arg placeholder conversion after resolve_skill_placeholders.++ resolve_skill_placeholders injects $ARGUMENTS (via {ARGS} expansion). A second+ _convert_argument_placeholder call must convert those to the agent's native format.+ """+ from specify_cli.agents import CommandRegistrar+ import copy++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"+ "Run: {SCRIPT}\n"+ )++ cmd_dir = project_dir / "preset" / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)+ (cmd_dir / "speckit.specify.md").write_text(+ "---\ndescription: forge wrap\nstrategy: wrap\n---\n\n"+ "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"+ )++ agent_dir = project_dir / ".forge" / "commands"+ agent_dir.mkdir(parents=True, exist_ok=True)++ registrar = CommandRegistrar()+ original = copy.deepcopy(registrar.AGENT_CONFIGS)+ registrar.AGENT_CONFIGS["test-forge-agent"] = {+ "dir": str(agent_dir.relative_to(project_dir)),+ "format": "markdown",+ "args": "{{parameters}}",+ "extension": ".md",+ "strip_frontmatter_keys": [],+ }+ try:+ registrar.register_commands(+ "test-forge-agent",+ [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],+ "test-preset",+ project_dir / "preset",+ project_dir,+ )+ finally:+ CommandRegistrar.AGENT_CONFIGS.clear()+ CommandRegistrar.AGENT_CONFIGS.update(original)++ written = (agent_dir / "speckit.specify.md").read_text()+ assert "{SCRIPT}" not in written+ assert "run.sh" in written+ # $ARGUMENTS injected by resolve_skill_placeholders must be re-converted+ assert "$ARGUMENTS" not in written+ assert "{{parameters}}" in written+++def _make_wrap_preset_dir(+ base: Path,+ preset_id: str,+ cmd_name: str,+ pre: str,+ post: str,+ aliases: list[str] | None = None,+ file_rel: str | None = None,+) -> Path:+ """Create a minimal wrap-strategy preset directory for testing."""+ preset_dir = base / preset_id+ cmd_dir = preset_dir / "commands"+ cmd_dir.mkdir(parents=True)+ file_rel = file_rel or f"commands/{cmd_name}.md"+ template = {+ "type": "command",+ "name": cmd_name,+ "file": file_rel,+ "description": f"{preset_id} wrap",+ }+ if aliases is not None:+ template["aliases"] = aliases+ manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": preset_id,+ "name": preset_id,+ "version": "1.0.0",+ "description": f"Preset {preset_id}",+ "author": "test",+ "repository": "https://example.com",+ "license": "MIT",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [template]+ },+ "tags": [],+ }+ import yaml as _yaml+ (preset_dir / "preset.yml").write_text(_yaml.dump(manifest))+ command_path = preset_dir / file_rel+ command_path.parent.mkdir(parents=True, exist_ok=True)+ command_path.write_text(+ f"---\ndescription: {preset_id} wrap\nstrategy: wrap\n---\n\n"+ f"[{pre}]\n\n{{CORE_TEMPLATE}}\n\n[{post}]\n"+ )+ return preset_dir+++class TestRemoveReconciliation:+ """Test that removing a preset re-registers the next layer's command."""++ def test_install_composes_extension_command_and_rewrites_subdir_paths_for_non_skill_agent(+ self, project_dir, temp_dir+ ):+ """When a preset overlays (append) an extension-provided base command,+ the initial composed non-skill-agent command file must have the+ extension's own subdir references rewritten to their installed+ location (#2101), matching the live repro: extension body+ 'Read agents/control/commander.md', preset appends to+ speckit.fakeext.cmd, generated Gemini content retains the bare path."""+ gemini_dir = project_dir / ".gemini" / "commands"+ gemini_dir.mkdir(parents=True)++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\ndescription: Extension fakeext cmd\n---\n\n"+ "Read agents/control/commander.md for context.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ preset_dir = temp_dir / "ext-cmd-append"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Append fakeext cmd\n---\n\n## Extra\n"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-cmd-append",+ "name": "Ext Cmd Append",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ "strategy": "append",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ cmd_files = list(gemini_dir.glob("*fakeext*"))+ assert cmd_files, "Command file should exist in gemini dir"+ content = cmd_files[0].read_text()+ assert ".specify/extensions/fakeext/agents/control/commander.md" in content+ assert "Read agents/control" not in content+ assert "## Extra" in contentdiff --git a/tests/specify_cli/presets/test_manager_skills.py b/tests/specify_cli/presets/test_manager_skills.pynew file mode 100644index 000000000..7ae833bfb--- /dev/null+++ b/tests/specify_cli/presets/test_manager_skills.py@@ -0,0 +1,2807 @@+"""Tests for preset skill artifacts in specify_cli.presets._manager_skills."""++import shutil+from pathlib import Path++import pytest+import yaml++from specify_cli.presets import PresetManager+from tests.specify_cli.presets._helpers import (+ PresetArtifactTestHelpers,+ install_self_test_preset,+)+++class TestPresetSkills(PresetArtifactTestHelpers):+ """Tests for preset skill registration and unregistration.++ Tests that install the self-test preset use ``install_self_test_preset``+ which scopes a narrow filter to the expected wrap-strategy warning.+ Reconciliation failures remain audible so real regressions surface.+ """++ def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):+ """When skills mode was used, a preset command override should update the skill."""+ # Simulate skills mode having been used: write init-options + create skill+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # Also create the claude commands dir so commands get registered+ (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)++ # Install self-test preset (has a command override for speckit.specify)+ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:self-test" in content, "Skill should reference preset source"+ assert "disable-model-invocation: false" in content++ # Verify it was recorded in registry, keyed by the active agent+ metadata = manager.registry.get("self-test")+ assert "speckit-specify" in metadata.get("registered_skills", {}).get("claude", [])++ def _install_arg_hint_preset(self, project_dir, temp_dir, ai, skills_dir, description, arg_hint):+ """Install a preset whose command declares argument-hint; return the SKILL.md path."""+ self._write_init_options(project_dir, ai=ai)+ self._create_skill(skills_dir, "speckit-hinttest-cmd")+ (project_dir / ".specify" / "extensions" / "hinttest").mkdir(parents=True, exist_ok=True)++ preset_dir = temp_dir / f"hint-preset-{ai}"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.hinttest.cmd.md").write_text(+ "---\n"+ f'description: "{description}"\n'+ f'argument-hint: "{arg_hint}"\n'+ "---\n\n"+ "Preset command body.\n",+ encoding="utf-8",+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": f"hint-preset-{ai}",+ "name": "Hint Preset",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.hinttest.cmd",+ "file": "commands/speckit.hinttest.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ return skills_dir / "speckit-hinttest-cmd" / "SKILL.md"++ def test_argument_hint_preserved_for_preset_command(self, project_dir, temp_dir):+ """argument-hint from a preset command must survive into the SKILL.md.++ Follow-up to #2903/#2916 for the preset skill generator. The+ description is long enough to fold across lines when serialized,+ guarding against an in-place string injection that would split the+ folded scalar into invalid YAML.+ """+ long_description = (+ "Build and maintain a lean, static context/ knowledge folder so "+ "coding agents load only what is relevant and save tokens"+ )+ arg_hint = "<init | update | list | check> [area] [slug] [-- notes]"+ skills_dir = project_dir / ".claude" / "skills"++ skill_file = self._install_arg_hint_preset(+ project_dir, temp_dir, "claude", skills_dir, long_description, arg_hint+ )+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ assert parsed["argument-hint"] == arg_hint+ assert parsed["description"] == long_description++ def test_argument_hint_not_added_for_non_claude_preset_command(self, project_dir, temp_dir):+ """Non-Claude skills agents must not receive argument-hint in preset skills."""+ arg_hint = "<init | update | list | check> [area]"+ skills_dir = project_dir / ".agents" / "skills"++ skill_file = self._install_arg_hint_preset(+ project_dir, temp_dir, "codex", skills_dir, "Build context", arg_hint+ )+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ assert "argument-hint" not in parsed++ def test_wrap_preset_inherits_argument_hint_from_core(self, project_dir, temp_dir):+ """A wrap-strategy preset that omits argument-hint must inherit it from the core template.++ Regression for issue #3991: the wrap-composition path in _register_skills+ previously inherited only scripts/agent_scripts from core_frontmatter,+ silently discarding argument-hint and leaking its value into description.+ """+ core_arg_hint = "Describe the feature you want to specify"+ preset_description = "Wrapped speckit.specify β extra project context added"+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # Place a core template that declares argument-hint+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\n"+ "description: Core specify description.\n"+ f'argument-hint: "{core_arg_hint}"\n'+ "---\n\n"+ "Core specify body.\n",+ encoding="utf-8",+ )++ # Wrap preset: only declares description (no argument-hint)+ preset_dir = temp_dir / "wrap-hint-preset"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.specify.md").write_text(+ "---\n"+ f'description: "{preset_description}"\n'+ "strategy: wrap\n"+ "---\n\n"+ "{CORE_TEMPLATE}\n",+ encoding="utf-8",+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "wrap-hint-preset",+ "name": "Wrap Hint Preset",+ "version": "1.0.0",+ "description": "Test wrap hint inheritance",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ "strategy": "wrap",+ }+ ]+ },+ }+ import yaml as _yaml+ with open(preset_dir / "preset.yml", "w") as f:+ _yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "1.0.0")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ # argument-hint must be inherited from core, not dropped+ assert parsed.get("argument-hint") == core_arg_hint, (+ f"argument-hint was not inherited from core; parsed={parsed}"+ )+ # description must be exactly the preset's declared value, not concatenated+ assert parsed["description"] == preset_description, (+ f"description was corrupted; parsed={parsed}"+ )++ def test_wrap_preset_inherits_argument_hint_for_unmapped_command(self, project_dir, temp_dir):+ """Wrap inheritance must carry argument-hint for a command NOT in ARGUMENT_HINTS.++ Regression guard for issue #3991. The companion test above wraps+ ``speckit.specify``, whose stem is in Claude's ``ARGUMENT_HINTS`` map, so+ the string-injection fallback in ``post_process_skill_content`` re-adds+ ``argument-hint`` even when wrap composition drops it β masking the bug.+ This test wraps an extension-like command (``speckit.myfeature``) that is+ absent from that map, so the *only* thing that can carry the hint into the+ SKILL.md is the wrap-composition inheritance fix itself. Without the fix+ the key is dropped and this test fails.+ """+ core_arg_hint = "Custom hint that lives only on the core template"+ preset_description = "Wrapped speckit.myfeature β extra project context added"+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-myfeature")++ # Place a core template (extension-like command) that declares argument-hint+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "myfeature.md").write_text(+ "---\n"+ "description: Core myfeature description.\n"+ f'argument-hint: "{core_arg_hint}"\n'+ "---\n\n"+ "Core myfeature body.\n",+ encoding="utf-8",+ )++ # Wrap preset: only declares description (no argument-hint)+ preset_dir = temp_dir / "wrap-hint-preset-unmapped"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.myfeature.md").write_text(+ "---\n"+ f'description: "{preset_description}"\n'+ "strategy: wrap\n"+ "---\n\n"+ "{CORE_TEMPLATE}\n",+ encoding="utf-8",+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "wrap-hint-preset-unmapped",+ "name": "Wrap Hint Preset Unmapped",+ "version": "1.0.0",+ "description": "Test wrap hint inheritance for an unmapped command",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.myfeature",+ "file": "commands/speckit.myfeature.md",+ "strategy": "wrap",+ }+ ]+ },+ }+ import yaml as _yaml+ with open(preset_dir / "preset.yml", "w") as f:+ _yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "1.0.0")++ skill_file = skills_dir / "speckit-myfeature" / "SKILL.md"+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ # argument-hint must be inherited from core, not dropped+ assert parsed.get("argument-hint") == core_arg_hint, (+ f"argument-hint was not inherited from core; parsed={parsed}"+ )+ # description must be exactly the preset's declared value, not concatenated+ assert parsed["description"] == preset_description, (+ f"description was corrupted; parsed={parsed}"+ )++ def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):+ """Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).++ ``_register_skills()`` previously ran only ``resolve_skill_placeholders()``,+ so command cross-references leaked into SKILL.md as raw placeholders+ instead of rendering as ``/speckit-<cmd>`` like the command layer.+ """+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir,+ "cmdref-install",+ "speckit.specify",+ "Override specify",+ "Run `__SPECKIT_COMMAND_SPECIFY__` then `__SPECKIT_COMMAND_PLAN__`.\n",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked into SKILL.md"+ # Claude's invoke_separator is "-", so tokens render as /speckit-<cmd>.+ assert "/speckit-specify" in content+ assert "/speckit-plan" in content++ def test_restore_skill_resolves_command_refs(self, project_dir, temp_dir):+ """Skill restore on preset removal must also resolve command tokens (issue #2717)."""+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\n"+ "Then run `__SPECKIT_COMMAND_PLAN__`.\n"+ )++ preset_dir = self._create_command_preset(+ temp_dir,+ "cmdref-restore",+ "speckit.specify",+ "Override specify",+ "Override body\n",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.remove("cmdref-restore")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on restore"+ assert "/speckit-plan" in content++ def test_restore_skill_preserves_dollar_command_refs(self, project_dir, temp_dir):+ """Dollar-style core refs remain native when a preset skill is removed."""+ self._write_init_options(project_dir, ai="zcode")+ skills_dir = project_dir / ".zcode" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ raw_core = (+ "---\ndescription: Core specify\n---\n\n"+ "Then run `__SPECKIT_COMMAND_PLAN__`.\n"+ )+ (core_cmds / "specify.md").write_text(raw_core)++ preset_dir = self._create_command_preset(+ temp_dir,+ "dollar-cmdref-restore",+ "speckit.specify",+ "Override specify",+ "Override body\n",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.remove("dollar-cmdref-restore")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "$speckit-plan" in content+ assert "/speckit-plan" not in content++ def test_reconcile_override_skill_resolves_command_refs(self, project_dir, temp_dir):+ """Reconcile's project-override restore must resolve command tokens (issue #2717).++ When a preset that overrode a command is removed and a project override+ becomes the winning layer, ``_reconcile_skills`` rewrites the skill from+ the override body β which must also render ``__SPECKIT_COMMAND_*__`` tokens.+ """+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # Project override wins once the preset is removed; its body carries a+ # command cross-reference token. No core template exists for "specify",+ # so the skill is restored exclusively via the reconcile override branch.+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True, exist_ok=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override specify\n---\n\n"+ "Then run `__SPECKIT_COMMAND_PLAN__`.\n"+ )++ preset_dir = self._create_command_preset(+ temp_dir,+ "cmdref-reconcile",+ "speckit.specify",+ "Preset specify",+ "Preset body\n",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.remove("cmdref-reconcile")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "override:speckit.specify" in content, "skill should be restored from the project override"+ assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on reconcile"+ assert "/speckit-plan" in content++ def test_extension_restore_resolves_command_refs(self, project_dir, temp_dir):+ """Extension-backed skill restore must resolve command tokens (issue #2717).++ When a preset override is removed and the skill is restored from an+ extension command body, ``__SPECKIT_COMMAND_*__`` tokens in that body+ must render as slash-command invocations like the core-template path.+ """+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\ndescription: Extension fakeext cmd\n---\n\n"+ "Then run `__SPECKIT_COMMAND_PLAN__`.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ preset_dir = self._create_command_preset(+ temp_dir,+ "cmdref-ext-restore",+ "speckit.fakeext.cmd",+ "Override fakeext cmd",+ "Override body\n",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.remove("cmdref-ext-restore")++ content = (skills_dir / "speckit-fakeext-cmd" / "SKILL.md").read_text()+ assert "source: extension:fakeext" in content, "skill should be restored from the extension"+ assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on extension restore"+ assert "/speckit-plan" in content++ def test_core_command_override_skill_uses_preset_command_description(self, project_dir, temp_dir):+ """Preset skill overrides for core commands should keep preset frontmatter descriptions."""+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-taskstoissues")++ preset_dir = temp_dir / "taskstoissues-description"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.repro.taskstoissues.md").write_text(+ "---\n"+ "description: COMMAND-FRONTMATTER-DESCRIPTION\n"+ "---\n\n"+ "# Repro command body\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "taskstoissues-description",+ "name": "Taskstoissues Description",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.taskstoissues",+ "file": "commands/speckit.repro.taskstoissues.md",+ "description": "MANIFEST-DESCRIPTION",+ "replaces": "speckit.taskstoissues",+ "strategy": "replace",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"+ content = skill_file.read_text()+ assert "description: COMMAND-FRONTMATTER-DESCRIPTION" in content+ assert "Convert tasks from tasks.md into GitHub issues." not in content+ assert "source: preset:taskstoissues-description" in content++ def test_core_skill_restore_uses_core_command_description(self, project_dir, temp_dir):+ """Core skill restore should keep core command frontmatter descriptions."""+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-taskstoissues")++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "taskstoissues.md").write_text(+ "---\n"+ "description: CORE-FRONTMATTER-DESCRIPTION\n"+ "---\n\n"+ "core taskstoissues body\n"+ )+ preset_dir = self._create_command_preset(+ temp_dir,+ "taskstoissues-restore",+ "speckit.taskstoissues",+ "PRESET-FRONTMATTER-DESCRIPTION",+ "preset taskstoissues body\n",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.remove("taskstoissues-restore")++ skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"+ content = skill_file.read_text()+ assert "description: CORE-FRONTMATTER-DESCRIPTION" in content+ assert "Convert tasks from tasks.md into GitHub issues." not in content+ assert "source: templates/commands/taskstoissues.md" in content+ assert "core taskstoissues body" in content++ def test_override_skill_reconcile_uses_override_command_description(self, project_dir, temp_dir):+ """Override skill reconciliation should keep override frontmatter descriptions."""+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-taskstoissues")++ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.taskstoissues.md").write_text(+ "---\n"+ "description: OVERRIDE-FRONTMATTER-DESCRIPTION\n"+ "---\n\n"+ "override taskstoissues body\n"+ )+ preset_dir = self._create_command_preset(+ temp_dir,+ "taskstoissues-reconcile",+ "speckit.taskstoissues",+ "PRESET-FRONTMATTER-DESCRIPTION",+ "preset taskstoissues body\n",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"+ content = skill_file.read_text()+ assert "description: OVERRIDE-FRONTMATTER-DESCRIPTION" in content+ assert "Convert tasks from tasks.md into GitHub issues." not in content+ assert "source: override:speckit.taskstoissues" in content+ assert "override taskstoissues body" in content++ def test_skill_not_updated_when_ai_skills_disabled(self, project_dir, temp_dir):+ """When skills mode was NOT used, preset install should not touch skills."""+ self._write_init_options(project_dir, ai="qwen", ai_skills=False)+ skills_dir = project_dir / ".qwen" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="untouched")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ content = skill_file.read_text()+ assert "untouched" in content, "Skill should not be modified when ai_skills=False"++ def test_get_skills_dir_returns_none_for_non_string_ai(self, project_dir):+ """Corrupted init-options ai values should not crash preset skill resolution."""+ init_options = project_dir / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text('{"ai":["codex"],"ai_skills":true,"script":"sh"}')++ manager = PresetManager(project_dir)++ assert manager._get_skills_dir() is None++ def test_get_skills_dir_returns_none_for_non_dict_init_options(self, project_dir):+ """Corrupted non-dict init-options payloads should fail closed."""+ init_options = project_dir / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text("[]")++ manager = PresetManager(project_dir)++ assert manager._get_skills_dir() is None++ def test_skill_not_updated_without_init_options(self, project_dir, temp_dir):+ """When no init-options.json exists, preset install should not touch skills."""+ skills_dir = project_dir / ".qwen" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="untouched")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ file_content = skill_file.read_text()+ assert "untouched" in file_content++ def test_skill_restored_on_preset_remove(self, project_dir, temp_dir):+ """When a preset is removed, skills should be restored from core templates."""+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)++ # Set up core command template in the project so restoration works+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text("---\ndescription: Core specify command\n---\n\nCore specify body\n")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ # Verify preset content is in the skill+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:self-test" in skill_file.read_text()++ # Remove the preset+ manager.remove("self-test")++ # Skill should be restored (core specify.md template exists)+ assert skill_file.exists(), "Skill should still exist after preset removal"+ content = skill_file.read_text()+ assert "preset:self-test" not in content, "Preset content should be gone"+ assert "templates/commands/specify.md" in content, "Should reference core template"+ assert "disable-model-invocation: false" in content++ def test_skill_restored_on_preset_remove_without_project_core_templates(self, project_dir):+ """Removing a preset must restore core skills even when the project+ has no ``.specify/templates/commands`` directory of its own β which+ is the normal case, since ``specify init`` never populates it. The+ real core commands live in the bundled core_pack/repo-root templates+ tree, and restoration must fall back there instead of deleting the+ skill outright (#3928).+ """+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # The project_dir fixture's commands dir is empty, matching a real+ # project β specify init never populates project-local overrides+ # for unmodified core commands.+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ assert core_cmds.exists() and not any(core_cmds.iterdir())++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:self-test" in skill_file.read_text(encoding="utf-8")++ manager.remove("self-test")++ assert skill_file.exists(), "Core skill must be restored, not deleted"+ content = skill_file.read_text(encoding="utf-8")+ assert "preset:self-test" not in content+ assert "templates/commands/specify.md" in content+ assert "Create or update the feature specification" in content++ def test_extension_wins_over_bundled_core_on_preset_remove(+ self, project_dir, monkeypatch+ ):+ """When an installed extension owns the same skill name as a core+ command, removing a preset that overrode that skill must restore it+ from the extension, not silently from the bundled core template.+ Extensions are resolved ahead of bundled core elsewhere, and the+ bundled-core fallback added for #3928 must not replace that+ higher-priority layer.++ The extension-command namespace rules (``speckit.<ext>.<command>``)+ make a genuine end-to-end name collision with a core command+ cumbersome to construct through real manifests, so this stubs+ ``_build_extension_skill_restore_index`` to exercise the priority+ ordering in ``_unregister_skills_in_dir`` directly -- the code path+ under test doesn't care how the index entry was produced, only that+ it wins over the bundled-core fallback when present.+ """+ self._write_init_options(project_dir, ai="claude")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ # No project-local core template override β the normal case, and+ # the one that makes the bundled-core fallback kick in at all.+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ assert core_cmds.exists() and not any(core_cmds.iterdir())++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ ext_specify_file = extension_dir / "commands" / "specify.md"+ ext_specify_file.write_text(+ "---\ndescription: Extension specify command\n---\n\n"+ "extension:fakeext specify body\n"+ )++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:self-test" in skill_file.read_text(encoding="utf-8")++ fake_restore_index = {+ "speckit-specify": {+ "command_name": "speckit.fakeext.specify",+ "source_file": ext_specify_file,+ "source": "extension:fakeext",+ "extension_id": "fakeext",+ "extension_dir": extension_dir,+ }+ }+ monkeypatch.setattr(+ manager,+ "_build_extension_skill_restore_index",+ lambda: fake_restore_index,+ )++ manager.remove("self-test")++ assert skill_file.exists()+ content = skill_file.read_text(encoding="utf-8")+ assert "preset:self-test" not in content+ assert "source: extension:fakeext" in content+ assert "extension:fakeext specify body" in content+ assert "templates/commands/specify.md" not in content++ def test_skill_restored_on_remove_resolves_script_placeholders(self, project_dir):+ """Core restore should resolve {SCRIPT}/{ARGS} placeholders like other skill paths."""+ self._write_init_options(project_dir, ai="claude", ai_skills=True, script="sh")+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="old")+ (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\n"+ "description: Core specify command\n"+ "scripts:\n"+ " sh: .specify/scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n"+ "---\n\n"+ "Run:\n"+ "{SCRIPT}\n"+ )++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)+ manager.remove("self-test")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "{SCRIPT}" not in content+ assert "{ARGS}" not in content+ assert ".specify/scripts/bash/create-new-feature.sh --json \"$ARGUMENTS\"" in content++ def test_skill_not_overridden_when_skill_path_is_file(self, project_dir):+ """Preset install should skip non-directory skill targets."""+ self._write_init_options(project_dir, ai="qwen")+ skills_dir = project_dir / ".qwen" / "skills"+ skills_dir.mkdir(parents=True, exist_ok=True)+ (skills_dir / "speckit-specify").write_text("not-a-directory")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ assert (skills_dir / "speckit-specify").is_file()+ metadata = manager.registry.get("self-test")+ assert "speckit-specify" not in metadata.get("registered_skills", {}).get("qwen", [])++ def test_no_skills_registered_when_skills_mode_disabled(self, project_dir, temp_dir):+ """Skills should not be created when skills mode is disabled."""+ self._write_init_options(project_dir, ai="claude", ai_skills=False)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ metadata = manager.registry.get("self-test")+ assert metadata.get("registered_skills", {}) == {}++ def test_extension_skill_override_matches_hyphenated_multisegment_name(self, project_dir, temp_dir):+ """Preset overrides for speckit.<ext>.<cmd> should target speckit-<ext>-<cmd> skills."""+ self._write_init_options(project_dir, ai="codex")+ skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(skills_dir, "speckit-fakeext-cmd", body="untouched")+ (project_dir / ".specify" / "extensions" / "fakeext").mkdir(parents=True, exist_ok=True)++ preset_dir = temp_dir / "ext-skill-override"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-override\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-skill-override",+ "name": "Ext Skill Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"+ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:ext-skill-override" in content+ assert "name: speckit-fakeext-cmd" in content+ assert "# Speckit Fakeext Cmd Skill" in content++ metadata = manager.registry.get("ext-skill-override")+ assert "speckit-fakeext-cmd" in metadata.get("registered_skills", {}).get("codex", [])++ def test_extension_skill_restored_on_preset_remove(self, project_dir, temp_dir):+ """Preset removal should restore an extension-backed skill instead of deleting it."""+ self._write_init_options(project_dir, ai="codex")+ skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\n"+ "description: Extension fakeext cmd\n"+ "scripts:\n"+ " sh: ../../scripts/bash/setup-plan.sh --json \"{ARGS}\"\n"+ "---\n\n"+ "extension:fakeext\n"+ "Run {SCRIPT}\n"+ "Read agents/control/commander.md for context.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "author": "acme-corp",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ preset_dir = temp_dir / "ext-skill-restore"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-restore\n"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-skill-restore",+ "name": "Ext Skill Restore",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"+ assert "preset:ext-skill-restore" in skill_file.read_text()++ manager.remove("ext-skill-restore")++ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:ext-skill-restore" not in content+ assert "source: extension:fakeext" in content+ assert "extension:fakeext" in content+ assert '.specify/scripts/bash/setup-plan.sh --json "$ARGUMENTS"' in content+ # Extension-relative subdir references must resolve to their+ # installed location on restore too (#2101), not just on first+ # registration.+ assert ".specify/extensions/fakeext/agents/control/commander.md" in content+ assert "Read agents/control" not in content+ assert "# Fakeext Cmd Skill" in content++ assert yaml.safe_load(content.split("---", 2)[1])["metadata"]["author"] == "acme-corp"++ def test_skill_composed_over_extension_base_rewrites_subdir_paths(+ self, project_dir, temp_dir+ ):+ """When a preset composes (append) over an extension-provided base+ command, the resulting skill (read from the .composed output) must+ still resolve the extension's own subdir references (#2101), not+ just when the extension wins outright (replace)."""+ self._write_init_options(project_dir, ai="codex")+ skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\ndescription: Extension fakeext cmd\n---\n\n"+ "Read agents/control/commander.md for context.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ preset_dir = temp_dir / "ext-base-append-skill"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Preset overlay\n---\n\n## Extra\n"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-base-append-skill",+ "name": "Ext Base Append Skill",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ "strategy": "append",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"+ content = skill_file.read_text()+ assert ".specify/extensions/fakeext/agents/control/commander.md" in content+ assert "Read agents/control" not in content+ assert "## Extra" in content++ def test_preset_remove_skips_skill_dir_without_skill_file(self, project_dir, temp_dir):+ """Preset removal should not delete arbitrary directories missing SKILL.md."""+ self._write_init_options(project_dir, ai="codex")+ skills_dir = project_dir / ".agents" / "skills"+ stray_skill_dir = skills_dir / "speckit-fakeext-cmd"+ stray_skill_dir.mkdir(parents=True, exist_ok=True)+ note_file = stray_skill_dir / "notes.txt"+ note_file.write_text("user content", encoding="utf-8")++ preset_dir = temp_dir / "ext-skill-missing-file"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-missing-file\n"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "ext-skill-missing-file",+ "name": "Ext Skill Missing File",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager = PresetManager(project_dir)+ installed_preset_dir = manager.presets_dir / "ext-skill-missing-file"+ shutil.copytree(preset_dir, installed_preset_dir)+ manager.registry.add(+ "ext-skill-missing-file",+ {+ "version": "1.0.0",+ "source": str(preset_dir),+ "provides_templates": ["speckit.fakeext.cmd"],+ "registered_skills": ["speckit-fakeext-cmd"],+ "priority": 10,+ },+ )++ manager.remove("ext-skill-missing-file")++ assert stray_skill_dir.is_dir()+ assert note_file.read_text(encoding="utf-8") == "user content"++ def test_kimi_legacy_dotted_skill_override_still_applies(self, project_dir, temp_dir):+ """Preset overrides should still target legacy dotted-named skill dirs.++ This exercises legacy *naming* (``speckit.specify``) under the current+ ``.kimi-code/`` base β distinct from the legacy ``.kimi/`` *location*.+ """+ self._write_init_options(project_dir, ai="kimi")+ skills_dir = project_dir / ".kimi-code" / "skills"+ self._create_skill(skills_dir, "speckit.specify", body="untouched")++ (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit.specify" / "SKILL.md"+ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:self-test" in content+ assert "name: speckit.specify" in content++ metadata = manager.registry.get("self-test")+ assert "speckit.specify" in metadata.get("registered_skills", {}).get("kimi", [])++ def test_kimi_legacy_dotted_skill_reconciles_priority_winner(+ self, project_dir, temp_dir+ ):+ """Reconciliation must carry forward recorded legacy skill names."""+ self._write_init_options(project_dir, ai="kimi")+ skills_dir = project_dir / ".kimi-code" / "skills"+ self._create_skill(skills_dir, "speckit.specify", body="untouched")+ (project_dir / ".kimi-code" / "commands").mkdir(+ parents=True, exist_ok=True+ )++ higher_dir = self._create_command_preset(+ temp_dir,+ "higher-kimi-preset",+ "speckit.specify",+ "Higher preset",+ "Higher body",+ )+ lower_dir = self._create_command_preset(+ temp_dir,+ "lower-kimi-preset",+ "speckit.specify",+ "Lower preset",+ "Lower body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(higher_dir, "0.1.5", priority=10)+ manager.install_from_directory(lower_dir, "0.1.5", priority=20)++ skill_file = skills_dir / "speckit.specify" / "SKILL.md"+ for preset_id in ("higher-kimi-preset", "lower-kimi-preset"):+ manager.registry.update(+ preset_id,+ {"registered_skills": {"kimi": ["speckit.specify"]}},+ )+ skill_file.write_text(+ "---\nname: speckit.specify\n---\n\nLower body\n",+ encoding="utf-8",+ )+ manager._reconcile_skills(["speckit.specify"])++ assert "Higher body" in skill_file.read_text(encoding="utf-8"), (+ "reconciliation must replace lower-priority raw content in a "+ "recorded legacy dotted skill directory"+ )++ def test_kimi_legacy_dotted_skill_receives_project_override(+ self, project_dir, temp_dir+ ):+ """Project overrides must update the recorded legacy path in place."""+ self._write_init_options(project_dir, ai="kimi")+ skills_dir = project_dir / ".kimi-code" / "skills"+ self._create_skill(skills_dir, "speckit.specify", body="untouched")+ (project_dir / ".kimi-code" / "commands").mkdir(+ parents=True, exist_ok=True+ )++ preset_dir = self._create_command_preset(+ temp_dir,+ "kimi-override-preset",+ "speckit.specify",+ "Preset",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ manager.registry.update(+ "kimi-override-preset",+ {"registered_skills": {"kimi": ["speckit.specify"]}},+ )+ modern_skill_dir = skills_dir / "speckit-specify"+ if modern_skill_dir.exists():+ shutil.rmtree(modern_skill_dir)++ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Project override\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ manager._reconcile_skills(["speckit.specify"])++ legacy_file = skills_dir / "speckit.specify" / "SKILL.md"+ assert "Override body" in legacy_file.read_text(encoding="utf-8")+ assert not modern_skill_dir.exists(), (+ "legacy-only ownership must not create an untracked modern path"+ )++ def test_kimi_skill_updated_even_when_ai_skills_disabled(self, project_dir, temp_dir):+ """Kimi presets should still propagate command overrides to existing skills."""+ self._write_init_options(project_dir, ai="kimi", ai_skills=False)+ skills_dir = project_dir / ".kimi-code" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="untouched")++ (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:self-test" in content+ assert "name: speckit-specify" in content++ metadata = manager.registry.get("self-test")+ assert "speckit-specify" in metadata.get("registered_skills", {}).get("kimi", [])++ def test_kimi_new_skill_created_even_when_ai_skills_disabled(self, project_dir, temp_dir):+ """Kimi native skills should still receive brand-new preset commands."""+ self._write_init_options(project_dir, ai="kimi", ai_skills=False)+ skills_dir = project_dir / ".kimi-code" / "skills"+ skills_dir.mkdir(parents=True, exist_ok=True)++ preset_dir = temp_dir / "kimi-new-skill"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.research.md").write_text(+ "---\n"+ "description: Kimi research workflow\n"+ "---\n\n"+ "preset:kimi-new-skill\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "kimi-new-skill",+ "name": "Kimi New Skill",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.research",+ "file": "commands/speckit.research.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-research" / "SKILL.md"+ assert skill_file.exists()+ content = skill_file.read_text()+ assert "preset:kimi-new-skill" in content+ assert "name: speckit-research" in content++ metadata = manager.registry.get("kimi-new-skill")+ assert "speckit-research" in metadata.get("registered_skills", {}).get("kimi", [])++ def test_kimi_preset_skill_override_resolves_script_placeholders(self, project_dir, temp_dir):+ """Kimi preset skill overrides should resolve placeholders and rewrite project paths."""+ self._write_init_options(project_dir, ai="kimi", ai_skills=False, script="sh")+ skills_dir = project_dir / ".kimi-code" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="untouched")+ (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)++ preset_dir = temp_dir / "kimi-placeholder-override"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.specify.md").write_text(+ "---\n"+ "description: Kimi placeholder override\n"+ "scripts:\n"+ " sh: scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n"+ "---\n\n"+ "Execute `{SCRIPT}` for __AGENT__\n"+ "Review templates/checklist.md and memory/constitution.md\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "kimi-placeholder-override",+ "name": "Kimi Placeholder Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "{SCRIPT}" not in content+ assert "__AGENT__" not in content+ assert ".specify/scripts/bash/create-new-feature.sh --json \"$ARGUMENTS\"" in content+ assert ".specify/templates/checklist.md" in content+ assert ".specify/memory/constitution.md" in content+ assert "for kimi" in content++ def test_agy_skill_restored_on_preset_remove(self, project_dir, temp_dir):+ """Agy preset removal should restore native skills instead of deleting them."""+ self._write_init_options(project_dir, ai="agy", ai_skills=True)+ skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="before override")++ core_command = project_dir / ".specify" / "templates" / "commands" / "specify.md"+ core_command.write_text(+ "---\n"+ "description: Restored core specify workflow\n"+ "---\n\n"+ "restored core body\n"+ )++ preset_dir = temp_dir / "agy-override"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.specify.md").write_text(+ "---\n"+ "description: Agy override\n"+ "---\n\n"+ "preset agy body\n"+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "agy-override",+ "name": "Agy Override",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset agy body" in skill_file.read_text()++ assert manager.remove("agy-override") is True+ assert skill_file.exists()+ restored = skill_file.read_text()+ assert "restored core body" in restored+ assert "name: speckit-specify" in restored++ def test_preset_skill_registration_handles_non_dict_init_options(self, project_dir, temp_dir):+ """Non-dict init-options payloads should not crash preset install/remove flows."""+ init_options = project_dir / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text("[]")++ skills_dir = project_dir / ".qwen" / "skills"+ self._create_skill(skills_dir, "speckit-specify", body="untouched")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ skill_content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()+ assert "untouched" in skill_content++ def test_partial_skill_registration_is_persisted_before_later_failure(+ self, project_dir, temp_dir, monkeypatch+ ):+ """A successful earlier skill write remains tracked if a later read fails."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=False)+ commands_dir = project_dir / ".github" / "agents"+ commands_dir.mkdir(parents=True)++ preset_dir = self._create_multi_command_preset(+ temp_dir,+ "partial-skill-failure-preset",+ ["speckit.specify", "speckit.plan"],+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ original_read_text = Path.read_text++ def fail_plan_source(path, *args, **kwargs):+ if (+ path.name == "speckit.plan.md"+ and path.parent.name == "commands"+ and "partial-skill-failure-preset" in path.parts+ ):+ raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid")+ return original_read_text(path, *args, **kwargs)++ monkeypatch.setattr(Path, "read_text", fail_plan_source)+ manager.register_enabled_presets_for_agent("copilot")++ metadata = manager.registry.get("partial-skill-failure-preset")+ assert "speckit-specify" in metadata["registered_skills"].get(+ "copilot", []+ ), (+ "the first successful write must be persisted before the later "+ "template failure aborts the registration call"+ )+ monkeypatch.setattr(Path, "read_text", original_read_text)+ assert manager.remove("partial-skill-failure-preset") is True+ remaining_skill = (+ project_dir+ / ".github"+ / "skills"+ / "speckit-specify"+ / "SKILL.md"+ )+ assert (+ not remaining_skill.exists()+ or "preset:partial-skill-failure-preset"+ not in remaining_skill.read_text(encoding="utf-8")+ ), "persisted partial ownership must remain removable"++ def test_remove_cleans_native_skill_missing_from_partial_skill_map(+ self, project_dir, temp_dir+ ):+ """Command cleanup must cover native skills absent from a partial map."""+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ (project_dir / ".claude" / "skills").mkdir(parents=True)+ preset_dir = self._create_command_preset(+ temp_dir,+ "partial-agent-skill-map-preset",+ "speckit.partial-native",+ "Partial native skill",+ "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ metadata = manager.registry.get("partial-agent-skill-map-preset")+ assert metadata["registered_skills"].get("claude")++ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ (project_dir / ".agents" / "skills").mkdir(parents=True)++ from unittest.mock import patch++ with patch.object(+ PresetManager,+ "_register_skills",+ side_effect=RuntimeError("simulated skills phase failure"),+ ):+ manager.register_enabled_presets_for_agent("codex")++ codex_skill = (+ project_dir+ / ".agents"+ / "skills"+ / "speckit-partial-native"+ / "SKILL.md"+ )+ assert codex_skill.exists()+ metadata = manager.registry.get("partial-agent-skill-map-preset")+ assert "speckit.partial-native" in metadata[+ "registered_commands"+ ].get("codex", [])+ assert not metadata["registered_skills"].get("codex")++ assert manager.remove("partial-agent-skill-map-preset") is True+ assert not codex_skill.exists(), (+ "native skill written by the commands phase must not be orphaned "+ "when another agent makes registered_skills globally non-empty"+ )++ def test_skill_switch_then_remove_restores_every_skill_agent_dir(+ self, project_dir, temp_dir+ ):+ """Switching between two skill-mode agents before removing a preset+ must restore both agents' directories, not just the currently+ active one.++ ``registered_skills`` records exactly which agent directories the+ preset wrote to (``{agent_name: [skill_name, ...]}``); switching to+ codex and re-registering adds a "codex" entry alongside the+ original "claude" entry, so removal restores both. Before the+ provenance fix, ``_unregister_skills`` only restored the currently+ active agent's skills directory; a preset used first under Claude+ and later switched to Codex would have its Claude override left+ behind permanently on removal (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ # Native skill agents only materialize a *brand-new* preset skill+ # when their skills directory already exists (mirrors every other+ # skill test in this class); pre-create both agents' directories so+ # install and the later switch both find an existing skill to+ # overwrite via _register_commands/_register_skills.+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "multi-skill-agent-preset", "speckit.specify",+ "Multi skill agent test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:multi-skill-agent-preset" in claude_skill.read_text()++ # Switch the active agent to codex (a different skill-mode agent)+ # and re-register enabled presets for it, mirroring what+ # `integration use codex` does.+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")++ codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:multi-skill-agent-preset" in codex_skill.read_text(), (+ "sanity: switching to codex should rescaffold the preset there"+ )+ assert "preset:multi-skill-agent-preset" in claude_skill.read_text(), (+ "sanity: the previous agent's registration is preserved on switch"+ )++ metadata = manager.registry.get("multi-skill-agent-preset")+ registered_skills = metadata.get("registered_skills", {})+ assert set(registered_skills) == {"claude", "codex"}, (+ "registered_skills must record both agent directories this "+ "preset actually wrote to (#2948)"+ )++ assert manager.remove("multi-skill-agent-preset") is True++ for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):+ assert skill_file.exists(), f"{label} skill file should still exist after removal"+ content = skill_file.read_text()+ assert "preset:multi-skill-agent-preset" not in content, (+ f"{label}'s preset override must be restored on removal, "+ "not orphaned permanently (#2948)"+ )+ assert "Core specify body" in content++ def test_infer_legacy_skill_provenance_does_not_falsely_attribute_command_mode_copilot(+ self, project_dir, temp_dir+ ):+ """Broadening provenance inference to command-backed agents must not+ falsely attribute ownership to an agent's directory that has no+ preset-owned marker.++ Copilot stays in plain command mode throughout (no skills ever+ rendered there), so ``.github/skills`` never receives this+ preset's ``SKILL.md``. Probing copilot's skills directory anyway+ (now that inference isn't restricted to static ``/SKILL.md``+ agents) must find nothing there and must not invent a false+ ``"copilot"`` entry (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ # Copilot has never been active; its command directory holds an+ # unrelated file so the directory exists, but no skills directory+ # or SKILL.md was ever written for it.+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)++ preset_dir = self._create_command_preset(+ temp_dir, "no-false-attribution-preset", "speckit.specify",+ "No false attribution test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ manager.registry.update(+ "no-false-attribution-preset",+ {"registered_skills": ["speckit-specify"]},+ )++ # Rescaffold again for the same agent (claude) with unchanged+ # names, triggering the legacy migration path.+ manager.register_enabled_presets_for_agent("claude")++ metadata = manager.registry.get("no-false-attribution-preset")+ registered_skills = metadata.get("registered_skills")+ assert isinstance(registered_skills, dict)+ assert set(registered_skills) == {"claude"}, (+ "copilot must not appear in the migrated registry when it has "+ "never actually rendered this preset's skill β probing its "+ "directory for a marker match must not create a false "+ "attribution (#2948)"+ )+ assert not (project_dir / ".github" / "skills").exists(), (+ "no .github/skills directory should have been created as a "+ "side effect of probing for provenance (#2948)"+ )++ def test_infer_legacy_skill_provenance_skips_invalid_utf8(+ self, project_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skill_dir = (+ project_dir / ".claude" / "skills" / "speckit-specify"+ )+ skill_dir.mkdir(parents=True)+ (skill_dir / "SKILL.md").write_bytes(b"\xff")++ manager = PresetManager(project_dir)++ assert manager._infer_legacy_skill_provenance(+ ["speckit-specify"], "some-pack", "claude"+ ) == {"claude": ["speckit-specify"]}++ def test_infer_legacy_skill_provenance_excludes_home_outputs(+ self, project_dir, temp_dir, monkeypatch+ ):+ home = temp_dir / "home"+ monkeypatch.setattr(Path, "home", lambda: home)+ skill_dir = home / ".hermes" / "skills" / "speckit-specify"+ skill_dir.mkdir(parents=True)+ (skill_dir / "SKILL.md").write_text(+ "---\n"+ "metadata:\n"+ " source: preset:some-pack\n"+ "---\n\n"+ "Other project\n",+ encoding="utf-8",+ )++ manager = PresetManager(project_dir)+ inferred = manager._infer_legacy_skill_provenance(+ ["speckit-specify"], "some-pack", "claude"+ )++ assert inferred == {"claude": ["speckit-specify"]}+ assert skill_dir.exists()++ def test_remove_infers_legacy_flat_list_provenance_without_prior_rescaffold(+ self, project_dir, temp_dir+ ):+ """``preset remove`` on a legacy flat-list registry must restore+ every previously active agent's directory, not just the currently+ active one, even when it is the *very first* post-upgrade+ operation (no intervening ``use``/``upgrade``/rescaffold).++ Pre-#2948 registries recorded a flat ``registered_skills`` list+ because presets were rendered for every detected skill-mode agent+ at once, not just the active one. Migrating that legacy format to+ the per-agent dict form previously only happened as a side effect+ of ``register_enabled_presets_for_agent`` (i.e. a rescaffold or+ ``integration use``/``switch``). If the user's first action after+ upgrading is instead directly running ``preset remove``, the+ legacy branch of ``_unregister_skills`` restored only the+ currently active agent's directory (via ``_get_skills_dir()``),+ permanently leaving this preset's override in every other,+ previously active agent's directory (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "remove-legacy-no-rescaffold-preset", "speckit.specify",+ "Remove legacy no rescaffold test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:remove-legacy-no-rescaffold-preset" in claude_skill.read_text(), (+ "sanity: install should have written the override under "+ "claude's skill directory"+ )+ # Simulate the pre-#2948 "register for every detected agent"+ # install behaviour by also placing the marker under codex's+ # directory directly (mirroring the old, non-active-only+ # rendering that predates this PR).+ codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"+ codex_skill.write_text(claude_skill.read_text(), encoding="utf-8")++ # Simulate a pre-#2948 registry: a flat list with no per-agent+ # provenance, even though both directories actually hold this+ # preset's marker on disk.+ manager.registry.update(+ "remove-legacy-no-rescaffold-preset",+ {"registered_skills": ["speckit-specify"]},+ )++ # No intervening use/upgrade/rescaffold: remove() is the very+ # first operation run after the legacy registry was written.+ assert manager.remove("remove-legacy-no-rescaffold-preset") is True++ for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):+ assert skill_file.exists(), f"{label} skill file should still exist after removal"+ content = skill_file.read_text()+ assert "preset:remove-legacy-no-rescaffold-preset" not in content, (+ f"{label}'s preset override must be restored on removal "+ "even with no prior rescaffold to migrate the legacy "+ "flat-list format first β remove() must infer real "+ "per-agent ownership from on-disk provenance itself "+ "(#2948)"+ )+ assert "Core specify body" in content++ def test_symlinked_skills_dir_rejected_on_removal(self, project_dir, temp_dir):+ """Removal must validate a recorded skill directory before touching it.++ If an agent's skills directory is replaced with a symlink escaping+ the project root between install and removal, restoration must+ refuse to write/rmtree through it rather than trusting the+ recorded agent name blindly. The unsafe directory is skipped+ best-effort; removal still succeeds and doesn't crash (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")++ preset_dir = self._create_command_preset(+ temp_dir, "symlink-guard-preset", "speckit.specify",+ "Symlink guard test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ metadata = manager.registry.get("symlink-guard-preset")+ assert "speckit-specify" in metadata.get("registered_skills", {}).get("claude", [])++ # Simulate the claude skills directory being replaced with a symlink+ # that escapes the project root, containing an external+ # "speckit-specify" directory that must not be touched.+ outside_target = temp_dir / "outside-claude-skills"+ outside_skill_dir = outside_target / "speckit-specify"+ outside_skill_dir.mkdir(parents=True)+ sentinel = outside_skill_dir / "SKILL.md"+ sentinel.write_text("do-not-touch")+ shutil.rmtree(claude_skills_dir)+ claude_skills_dir.symlink_to(outside_target, target_is_directory=True)++ assert manager.remove("symlink-guard-preset") is True++ assert sentinel.read_text() == "do-not-touch", (+ "removal must not follow a symlinked skills directory outside "+ "the project root (#2948)"+ )+ assert outside_skill_dir.is_dir(), (+ "the external directory must not be rmtree'd through a "+ "symlinked skills path"+ )+ assert claude_skills_dir.is_symlink(), (+ "the symlink itself should be left alone, not rmtree'd through"+ )++ def test_preset_removal_does_not_touch_other_presets_skill_dir(+ self, project_dir, temp_dir+ ):+ """Removing a preset must only touch directories it actually wrote to.++ Preset A is installed while Claude is active and preset B is+ installed while Codex is active; both override the same command+ name, so both materialize a ``speckit-specify`` skill, but in+ *different* agent directories. Before the provenance fix, removing+ B enumerated every existing skill-mode directory (including+ Claude's) and restored/overwrote anything named ``speckit-specify``+ found there, corrupting A's override even though B never touched+ Claude's directory (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_skills_dir, "speckit-specify")++ preset_a_dir = self._create_command_preset(+ temp_dir, "preset-a", "speckit.specify", "Preset A", "preset A body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_a_dir, "0.1.5")++ claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:preset-a" in claude_skill_file.read_text()++ # Switch to codex and install a second preset overriding the same+ # command; codex's skills directory is entirely separate.+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")++ preset_b_dir = self._create_command_preset(+ temp_dir, "preset-b", "speckit.specify", "Preset B", "preset B body",+ )+ manager.install_from_directory(preset_b_dir, "0.1.5")++ metadata_b = manager.registry.get("preset-b")+ assert "claude" not in metadata_b.get("registered_skills", {}), (+ "preset B never wrote to claude's skills directory and must "+ "not record it as touched"+ )++ assert manager.remove("preset-b") is True++ assert "preset:preset-a" in claude_skill_file.read_text(), (+ "removing preset B must not disturb preset A's Claude override (#2948)"+ )++ def test_remove_does_not_recreate_empty_skill_dir(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-orphan")+ preset_dir = self._create_command_preset(+ temp_dir,+ "orphan-skill-preset",+ "speckit.orphan",+ "Orphan",+ "Preset-only body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ skill_dir = skills_dir / "speckit-orphan"+ assert skill_dir.exists()+ assert manager.remove("orphan-skill-preset") is True+ assert not skill_dir.exists()++ def test_remove_preserves_non_owned_skill_during_reconciliation(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ self._create_skill(skills_dir, "speckit-specify")++ lower_dir = self._create_command_preset(+ temp_dir,+ "non-owned-lower-preset",+ "speckit.specify",+ "Lower",+ "Lower preset body",+ )+ higher_dir = self._create_command_preset(+ temp_dir,+ "non-owned-higher-preset",+ "speckit.specify",+ "Higher",+ "Higher preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(lower_dir, "0.1.5", priority=10)+ manager.install_from_directory(higher_dir, "0.1.5", priority=1)++ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ skill_file.write_text(+ "---\nname: speckit-specify\n---\n\nUser-owned body\n",+ encoding="utf-8",+ )++ assert manager.remove("non-owned-higher-preset") is True+ assert skill_file.read_text(encoding="utf-8") == (+ "---\nname: speckit-specify\n---\n\nUser-owned body\n"+ )++ def test_shared_skills_dir_restored_once_using_active_agent(+ self, project_dir, temp_dir+ ):+ """Removal must restore a physical skills directory shared by+ multiple agents exactly once, using the active agent's renderer.++ Codex and Antigravity (agy) both resolve their skills directory to+ ``.agents/skills``. Registering a preset under codex, switching to+ agy, then switching back to codex records provenance for *both*+ agent keys even though they share one physical directory. Before+ the fix, ``_unregister_skills`` restored once per recorded agent+ key rather than once per unique directory, so the directory was+ written twice on removal with whichever agent was iterated *last*+ silently winning β regardless of which agent is actually active+ (#2948).+ """+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ shared_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(shared_skills_dir, "speckit-specify")++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ preset_dir = self._create_command_preset(+ temp_dir, "shared-dir-preset", "speckit.specify",+ "Shared dir test", "preset body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ # Switch to agy (shares .agents/skills with codex) and back to+ # codex, mirroring `integration use agy` then `integration use+ # codex`. Both agent keys end up recorded in registered_skills even+ # though they refer to the same physical directory.+ self._write_init_options(project_dir, ai="agy", ai_skills=True)+ manager.register_enabled_presets_for_agent("agy")+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ manager.register_enabled_presets_for_agent("codex")++ metadata = manager.registry.get("shared-dir-preset")+ registered_skills = metadata.get("registered_skills", {})+ assert set(registered_skills) == {"codex", "agy"}, (+ "both agent keys must be recorded even though they share one "+ "physical directory (#2948)"+ )++ from unittest.mock import patch++ # Exercise `_unregister_skills` directly (the method this fix+ # changed) rather than the full `remove()` flow, which separately+ # triggers post-removal reconciliation that may also touch the+ # active agent's directory β an unrelated call this test isn't+ # targeting.+ with patch.object(+ manager,+ "_unregister_skills_in_dir",+ wraps=manager._unregister_skills_in_dir,+ ) as spy:+ manager._unregister_skills(registered_skills, preset_dir)++ assert spy.call_count == 1, (+ "a physical directory shared by multiple recorded agents must "+ "be restored exactly once, not once per agent key (#2948)"+ )+ (_names, called_dir, called_agent), _kwargs = spy.call_args+ assert called_dir == shared_skills_dir+ assert called_agent == "codex", (+ "the currently active agent must be used as the renderer when "+ "it shares the restored directory, not whichever agent was "+ "recorded last (#2948)"+ )++ skill_file = shared_skills_dir / "speckit-specify" / "SKILL.md"+ content = skill_file.read_text()+ assert "preset:shared-dir-preset" not in content+ assert "Core specify body" in content++ def test_remove_higher_priority_skills_only_preset_restores_lower_preset(+ self, project_dir, temp_dir+ ):+ """Removing a skills-mode preset must reconcile against the surviving+ stack, not fall back to core/extension content.++ Copilot in skills mode never populates ``registered_commands`` for+ its overrides (``_register_commands``'s ``ai_skills`` guard skips+ command-file registration entirely), so with two presets overriding+ the same command, the removed preset's command name was never added+ to ``removed_cmd_names`` and reconciliation was skipped outright.+ ``_unregister_skills`` then restored straight to core/extension+ content instead of resolving the lower-priority preset that should+ now win (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)++ preset_a_dir = self._create_command_preset(+ temp_dir, "skills-preset-a", "speckit.specify",+ "Preset A", "preset A body",+ )+ preset_b_dir = self._create_command_preset(+ temp_dir, "skills-preset-b", "speckit.specify",+ "Preset B", "preset B body",+ )++ manager = PresetManager(project_dir)+ # Lower priority number = higher precedence.+ manager.install_from_directory(preset_a_dir, "0.1.5", priority=5)+ manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)++ skills_dir = project_dir / ".github" / "skills"+ skill_file = skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:skills-preset-a" in skill_file.read_text(), (+ "sanity: the higher-precedence preset should win initially"+ )++ assert manager.remove("skills-preset-a") is True++ content = skill_file.read_text()+ assert "preset:skills-preset-b" in content, (+ "removing the higher-precedence skills-mode preset must "+ "restore the surviving lower-precedence preset's override, "+ "not fall back to core/extension content (#2948)"+ )+ assert "preset:skills-preset-a" not in content++ def test_remove_reconciles_skill_for_every_historical_agent(+ self, project_dir, temp_dir+ ):+ """Removing a preset must reconcile every historical skills+ directory its ``registered_skills`` actually targeted, not only+ the currently active one.++ Preset B (survives) is installed while claude is active, then+ preset A (higher precedence) overrides the same command while+ claude is still active. Switching to codex and rescaffolding+ records codex too, so preset A's ``registered_skills`` spans both+ claude (now inactive) and codex (active) directories. Removing A+ restores both directories to core/extension via+ ``_unregister_skills``, but ``_reconcile_skills`` used to only+ resolve/apply the surviving winner for the currently active+ skills directory, leaving claude's directory reverted to+ core/extension content instead of preset B's override (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"++ # A core template fallback is required so unregistering the+ # top-priority preset's SKILL.md restores core content rather than+ # deleting the skill directory outright when no preset remains to+ # apply on top of it (mirrors the pre-existing skills-reconciliation+ # fixtures elsewhere in this file).+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ preset_b_dir = self._create_command_preset(+ temp_dir, "hist-skill-preset-b", "speckit.specify",+ "Preset B", "preset B body",+ )+ preset_a_dir = self._create_command_preset(+ temp_dir, "hist-skill-preset-a", "speckit.specify",+ "Preset A", "preset A body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)+ manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)++ claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert "preset:hist-skill-preset-a" in claude_skill_file.read_text(), (+ "sanity: preset A (higher precedence) should win initially"+ )++ # Switch the active integration to codex (a distinct skills+ # directory) and rescaffold, mirroring `integration use codex`.+ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ codex_skills_dir = project_dir / ".agents" / "skills"+ manager.register_enabled_presets_for_agent("codex")++ metadata_a = manager.registry.get("hist-skill-preset-a")+ assert set(metadata_a.get("registered_skills", {})) == {"claude", "codex"}, (+ "sanity: preset A's registered_skills must span both the "+ "historical (claude) and currently active (codex) agents"+ )++ assert manager.remove("hist-skill-preset-a") is True++ codex_skill_file = codex_skills_dir / "speckit-specify" / "SKILL.md"+ assert claude_skill_file.exists(), "claude's skill file must still exist after removal"+ assert codex_skill_file.exists(), "codex's skill file must still exist after removal"+ assert "preset:hist-skill-preset-b" in claude_skill_file.read_text(), (+ "removing the higher-precedence preset must restore the "+ "surviving preset's override in the historical (inactive) "+ "agent's directory too, not only the active agent's (#2948)"+ )+ assert "preset:hist-skill-preset-b" in codex_skill_file.read_text(), (+ "the surviving preset's override must also be restored for "+ "the currently active agent"+ )++ def test_skill_reconciliation_preserves_per_directory_names(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_dir = project_dir / ".claude" / "skills"+ self._create_skill(claude_dir, "speckit-alpha")+ alpha_dir = self._create_command_preset(+ temp_dir, "partial-alpha", "speckit.alpha",+ "Alpha", "alpha body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(alpha_dir, "0.1.5")++ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ codex_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_dir, "speckit-beta")+ beta_dir = self._create_command_preset(+ temp_dir, "partial-beta", "speckit.beta",+ "Beta", "beta body",+ )+ manager.install_from_directory(beta_dir, "0.1.5")++ affected = manager._unregister_skills(+ {+ "claude": ["speckit-alpha"],+ "codex": ["speckit-beta"],+ },+ manager.presets_dir / "partial-alpha",+ )+ manager._reconcile_skills(+ ["speckit.alpha", "speckit.beta"],+ extra_skills_dirs=affected,+ )++ assert (claude_dir / "speckit-alpha" / "SKILL.md").exists()+ assert (codex_dir / "speckit-beta" / "SKILL.md").exists()+ assert not (claude_dir / "speckit-beta").exists()+ assert not (codex_dir / "speckit-alpha").exists()++ def test_skill_reconciliation_rejects_unsafe_managed_names(+ self, project_dir, temp_dir+ ):+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ skills_dir.mkdir(parents=True)+ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )+ absolute_escape = temp_dir / "absolute-escape"+ traversal_escape = project_dir / ".claude" / "traversal-escape"++ manager = PresetManager(project_dir)+ manager._reconcile_skills(+ ["speckit.specify"],+ extra_skills_dirs={+ skills_dir: (+ "claude",+ [str(absolute_escape), "../traversal-escape"],+ )+ },+ )++ assert not absolute_escape.exists()+ assert not traversal_escape.exists()++ def test_remove_reconciliation_tracks_new_historical_skill_agent_for_survivor(+ self, project_dir, temp_dir+ ):+ """Historical-agent skill reconciliation writes must be recorded in+ the surviving preset's own ``registered_skills``, mirroring+ ``test_remove_reconciliation_tracks_new_historical_agent_for_survivor``+ for the command side.++ Preset A is installed while claude is active, then survives to be+ active under codex too (so A's ``registered_skills`` spans both+ claude and codex). Preset B is installed *only* while codex is+ active β B's ``registered_skills`` is ``{"codex": [...]}`` and+ never mentions claude. Removing A triggers reconciliation that+ renders B's SKILL.md into claude's directory (an agent B never+ wrote to before) via ``extra_skills_dirs``, but if that write+ isn't merged back into B's own ``registered_skills``, a later+ ``remove('b')`` only cleans up codex, leaving claude's SKILL.md β+ rendered there entirely by side effect of removing A β untracked+ by any preset (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ # Pre-create the skill so _register_commands/_register_skills find+ # an existing skill to overwrite (mirrors every other skill test+ # in this class β native skill agents only overwrite already+ # existing skill directories, they don't materialize brand-new+ # ones outside of active-agent creation).+ self._create_skill(claude_skills_dir, "speckit-specify")++ core_cmds = project_dir / ".specify" / "templates" / "commands"+ core_cmds.mkdir(parents=True, exist_ok=True)+ (core_cmds / "specify.md").write_text(+ "---\ndescription: Core specify command\n---\n\nCore specify body\n",+ encoding="utf-8",+ )++ preset_a_dir = self._create_command_preset(+ temp_dir, "orphan-skill-preset-a", "speckit.specify",+ "Preset A", "preset A body",+ )+ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)++ self._write_init_options(project_dir, ai="codex", ai_skills=True)+ codex_skills_dir = project_dir / ".agents" / "skills"+ self._create_skill(codex_skills_dir, "speckit-specify")+ manager.register_enabled_presets_for_agent("codex")++ metadata_a = manager.registry.get("orphan-skill-preset-a")+ assert set(metadata_a.get("registered_skills", {})) == {"claude", "codex"}, (+ "sanity: preset A must be tracked under both agents"+ )++ # Preset B is installed only now, while codex is the sole active+ # agent β it never writes to or tracks claude.+ preset_b_dir = self._create_command_preset(+ temp_dir, "orphan-skill-preset-b", "speckit.specify",+ "Preset B", "preset B body",+ )+ manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)++ metadata_b = manager.registry.get("orphan-skill-preset-b")+ assert set(metadata_b.get("registered_skills", {})) == {"codex"}, (+ "sanity: preset B must only be tracked for codex before "+ "preset A is removed"+ )++ assert manager.remove("orphan-skill-preset-a") is True++ claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"+ assert claude_skill_file.exists(), (+ "sanity: claude's skill file must have been restored by "+ "reconciliation"+ )+ assert "preset:orphan-skill-preset-b" in claude_skill_file.read_text(), (+ "sanity: claude's SKILL.md must reflect preset B's content "+ "after preset A is removed"+ )++ metadata_b = manager.registry.get("orphan-skill-preset-b")+ assert set(metadata_b.get("registered_skills", {})) == {"claude", "codex"}, (+ "preset B's own registered_skills must be updated to include "+ "claude once reconciliation actually renders content there "+ "on its behalf β otherwise B's registry entry silently lies "+ "about which directories it owns (#2948)"+ )++ assert manager.remove("orphan-skill-preset-b") is True++ # No preset is installed any more, so claude's SKILL.md must have+ # been reconciled down to the core bundled template (or removed+ # entirely) β but it must NOT still contain B's stale content,+ # which would mean B's write there was never tracked for cleanup.+ if claude_skill_file.exists():+ assert "preset:orphan-skill-preset-b" not in claude_skill_file.read_text(), (+ "removing preset B must clean up claude's directory too, "+ "since B's registered_skills was updated to include it β "+ "otherwise B's stale content is orphaned there forever "+ "with no preset left to track or clean it up (#2948)"+ )++ def test_symlinked_skill_subdir_rejected_on_restore(self, project_dir, temp_dir):+ """Restore must validate each per-skill subdirectory, not just its parent.++ ``_safe_skills_dir_for_agent`` only validates the parent skills+ directory (e.g. ``.claude/skills``); a symlink planted one level+ deeper at the individual skill's own subdirectory (e.g.+ ``.claude/skills/speckit-specify``) has a perfectly safe parent and+ would otherwise slip past that check, since ``is_dir()`` follows+ symlinks. Restoration must refuse to write/rmtree through it (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ claude_skills_dir.mkdir(parents=True)++ outside_target = temp_dir / "outside-skill-subdir"+ outside_target.mkdir()+ sentinel = outside_target / "SKILL.md"+ sentinel.write_text("do-not-touch")+ (claude_skills_dir / "speckit-specify").symlink_to(+ outside_target, target_is_directory=True+ )++ manager = PresetManager(project_dir)+ manager._unregister_skills_in_dir(+ ["speckit-specify"], claude_skills_dir, "claude"+ )++ assert sentinel.read_text() == "do-not-touch", (+ "restoration must not follow a symlinked skill subdirectory "+ "to write/delete outside the project (#2948)"+ )+ assert (claude_skills_dir / "speckit-specify").is_symlink(), (+ "the symlink itself should be left alone, not rmtree'd through"+ )++ def test_symlinked_skill_subdir_rejected_on_write(self, project_dir, temp_dir):+ """Registration must validate each per-skill subdirectory before writing.++ A symlink planted at an individual skill's own subdirectory (safe+ parent, unsafe leaf) would otherwise pass the existing+ ``skill_subdir.exists() and not skill_subdir.is_dir()`` guard+ (``is_dir()`` follows symlinks) and have ``SKILL.md`` written+ through it to an arbitrary location (#2948).+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ copilot_commands_dir = project_dir / ".github" / "agents"+ copilot_commands_dir.mkdir(parents=True)+ skills_dir = project_dir / ".github" / "skills"+ skills_dir.mkdir(parents=True)++ outside_target = temp_dir / "outside-skill-write-target"+ outside_target.mkdir()+ (skills_dir / "speckit-specify").symlink_to(+ outside_target, target_is_directory=True+ )++ preset_dir = self._create_command_preset(+ temp_dir, "symlink-write-preset", "speckit.specify",+ "Symlink write test", "preset body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ assert not (outside_target / "SKILL.md").exists(), (+ "registration must not follow a symlinked skill subdirectory "+ "to write outside the project (#2948)"+ )+ assert (skills_dir / "speckit-specify").is_symlink(), (+ "the symlink itself should be left alone"+ )++ def test_symlinked_skill_file_rejected_on_write(self, project_dir, temp_dir):+ """Registration must not follow a symlinked SKILL.md destination."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ (project_dir / ".github" / "agents").mkdir(parents=True)+ skill_dir = (+ project_dir / ".github" / "skills" / "speckit-specify"+ )+ skill_dir.mkdir(parents=True)+ outside_file = temp_dir / "outside-registration.md"+ outside_file.write_text("do-not-touch", encoding="utf-8")+ (skill_dir / "SKILL.md").symlink_to(outside_file)++ preset_dir = self._create_command_preset(+ temp_dir,+ "symlink-file-write-preset",+ "speckit.specify",+ "Symlink file write",+ "preset body",+ )+ manager = PresetManager(project_dir)+ with pytest.raises(ValueError):+ manager.install_from_directory(preset_dir, "0.1.5")++ assert outside_file.read_text(encoding="utf-8") == "do-not-touch"+ assert (skill_dir / "SKILL.md").is_symlink()++ def test_symlinked_skill_file_rejected_on_restore(+ self, project_dir, temp_dir+ ):+ """Restoration must not follow a symlinked SKILL.md destination."""+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ core_commands = project_dir / ".specify" / "templates" / "commands"+ (core_commands / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )+ skill_dir = (+ project_dir / ".claude" / "skills" / "speckit-specify"+ )+ skill_dir.mkdir(parents=True)+ outside_file = temp_dir / "outside-restoration.md"+ outside_file.write_text("do-not-touch", encoding="utf-8")+ (skill_dir / "SKILL.md").symlink_to(outside_file)++ manager = PresetManager(project_dir)+ with pytest.raises(ValueError):+ manager._unregister_skills_in_dir(+ ["speckit-specify"], skill_dir.parent, "claude"+ )++ assert outside_file.read_text(encoding="utf-8") == "do-not-touch"+ assert (skill_dir / "SKILL.md").is_symlink()++ def test_symlinked_skill_file_rejected_on_override_reconcile(+ self, project_dir, temp_dir+ ):+ """Project-override reconciliation must not follow SKILL.md symlinks."""+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skill_dir = (+ project_dir / ".github" / "skills" / "speckit-specify"+ )+ skill_dir.mkdir(parents=True)+ outside_file = temp_dir / "outside-reconciliation.md"+ outside_file.write_text("do-not-touch", encoding="utf-8")+ (skill_dir / "SKILL.md").symlink_to(outside_file)++ preset_dir = self._create_command_preset(+ temp_dir,+ "symlink-override-preset",+ "speckit.specify",+ "Preset",+ "Preset body",+ )+ manager = PresetManager(project_dir)+ manager.registry.add(+ "symlink-override-preset",+ {+ "version": "1.0.0",+ "source": "local",+ "enabled": True,+ "priority": 10,+ "registered_commands": {},+ "registered_skills": {+ "copilot": ["speckit-specify"]+ },+ },+ )+ installed_dir = (+ manager.presets_dir / "symlink-override-preset"+ )+ shutil.copytree(preset_dir, installed_dir)+ overrides_dir = (+ project_dir / ".specify" / "templates" / "overrides"+ )+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "speckit.specify.md").write_text(+ "---\ndescription: Override\n---\n\nOverride body\n",+ encoding="utf-8",+ )++ manager._reconcile_skills(["speckit.specify"])++ assert outside_file.read_text(encoding="utf-8") == "do-not-touch"+ assert (skill_dir / "SKILL.md").is_symlink()++ def test_is_safe_registry_skill_name_rejects_unsafe_values(self, project_dir):+ """Unit-test the centralized registry skill-name boundary guard.++ ``registered_skills`` entries are persisted registry data, not+ manifest-derived, so every preset cleanup/provenance loop that+ joins one onto a directory must first reject: non-strings, empty+ strings, absolute paths, multi-component paths (containing ``/``),+ and the literal traversal components ``"."``/``".."`` β the last+ of which is *not* caught by a naive ``is_absolute() or+ len(parts) != 1`` check alone, since ``Path("..").parts`` is a+ single-element tuple (#2948).+ """+ manager = PresetManager(project_dir)+ is_safe = manager._is_safe_registry_skill_name++ assert is_safe("speckit-specify") is True+ assert is_safe("") is False+ assert is_safe(None) is False+ assert is_safe(123) is False+ assert is_safe(["speckit-specify"]) is False+ assert is_safe(".") is False+ assert is_safe("..") is False+ assert is_safe("/etc/passwd") is False+ assert is_safe(str(project_dir / "important-data")) is False+ assert is_safe("foo/bar") is False+ assert is_safe("foo/..") is False+ assert is_safe("../foo") is False++ def test_unregister_skills_rejects_unknown_agent_provenance(+ self, project_dir+ ):+ """Unknown registry agent keys must not fall back to shared skills."""+ shared_skills_dir = project_dir / ".agents" / "skills"+ skill_dir = self._create_skill(+ shared_skills_dir, "speckit-specify", "user-owned content"+ )+ core_commands = project_dir / ".specify" / "templates" / "commands"+ (core_commands / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )++ manager = PresetManager(project_dir)+ manager._unregister_skills(+ {"unknown": ["speckit-specify"]}, project_dir+ )++ assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (+ "---\nname: speckit-specify\n---\n\nuser-owned content\n"+ )++ def test_unregister_legacy_fallback_skips_non_owned_skill(+ self, project_dir+ ):+ """Legacy fallback provenance must not overwrite a user-owned skill."""+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ skill_dir = self._create_skill(+ skills_dir, "speckit-specify", "user-owned content"+ )+ core_commands = project_dir / ".specify" / "templates" / "commands"+ (core_commands / "specify.md").write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )++ manager = PresetManager(project_dir)+ manager._unregister_skills(+ ["speckit-specify"], "removed-preset"+ )++ assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (+ "---\nname: speckit-specify\n---\n\nuser-owned content\n"+ )++ def test_unregister_skills_in_dir_unreadable_core_template_skips(+ self, project_dir+ ):+ """An undecodable core template must not crash `preset remove`.++ Every other failure in the restore loop β an unsafe registry name,+ a missing skill subdirectory, a foreign owner β skips the skill+ with ``continue``. The core-template read was outside that+ boundary, so one non-UTF-8 project-owned override in+ ``.specify/templates/commands/`` raised a raw ``UnicodeDecodeError``+ straight out of ``PresetManager.remove()``, which has no handler+ for it. Sibling reads of the very same directory are already+ guarded (``_substitute_core_template``, the provenance reads in+ ``_infer_legacy_skill_provenance``).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ skill_dir = self._create_skill(+ skills_dir, "speckit-specify", "installed content"+ )+ core_commands = project_dir / ".specify" / "templates" / "commands"+ core_commands.mkdir(parents=True, exist_ok=True)+ (core_commands / "specify.md").write_bytes(+ b"---\ndescription: \xff\xfe not utf-8\n---\n\nCore body\n"+ )++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="speckit-specify"):+ mutated = manager._unregister_skills_in_dir(+ ["speckit-specify"], skills_dir, "claude"+ )++ assert mutated == [], (+ "a skill whose restore source could not be read was not "+ "restored, so it must not be reported as mutated"+ )+ assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (+ "---\nname: speckit-specify\n---\n\ninstalled content\n"+ ), (+ "an unreadable core template must leave the skill untouched β "+ "falling through to the rmtree branch would delete it exactly "+ "when its replacement cannot be generated"+ )++ def test_unregister_skills_in_dir_unreadable_core_template_oserror_skips(+ self, project_dir, monkeypatch+ ):+ """The same boundary must cover ``OSError`` (e.g. permission denied).++ Mocked rather than chmod-based so the case also holds under+ privileged CI, where permission bits are not enforced.+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ skill_dir = self._create_skill(+ skills_dir, "speckit-specify", "installed content"+ )+ core_commands = project_dir / ".specify" / "templates" / "commands"+ core_commands.mkdir(parents=True, exist_ok=True)+ core_template = core_commands / "specify.md"+ core_template.write_text(+ "---\ndescription: Core specify\n---\n\nCore body\n",+ encoding="utf-8",+ )++ original_read_text = Path.read_text++ def failing_read_text(self_path, *args, **kwargs):+ if self_path == core_template:+ raise PermissionError(13, "Permission denied")+ return original_read_text(self_path, *args, **kwargs)++ monkeypatch.setattr(Path, "read_text", failing_read_text)++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="speckit-specify"):+ mutated = manager._unregister_skills_in_dir(+ ["speckit-specify"], skills_dir, "claude"+ )++ monkeypatch.undo()++ assert mutated == []+ assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (+ "---\nname: speckit-specify\n---\n\ninstalled content\n"+ )++ def test_unregister_skills_in_dir_unreadable_extension_source_skips(+ self, project_dir+ ):+ """The extension-restore arm needs the same boundary as the core arm.++ The two restore reads are independent branches β a skill backed by an+ installed extension never reaches the core-template read β so this+ half of the guard can regress on its own. An undecodable extension+ command file must warn, leave the skill byte-for-byte intact, and stay+ out of ``mutated_names``.+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ skills_dir = project_dir / ".claude" / "skills"+ skill_dir = self._create_skill(+ skills_dir, "speckit-fakeext-cmd", "installed content"+ )++ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "commands" / "cmd.md").write_bytes(+ b"---\ndescription: \xff\xfe not utf-8\n---\n\nExtension body\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="speckit-fakeext-cmd"):+ mutated = manager._unregister_skills_in_dir(+ ["speckit-fakeext-cmd"], skills_dir, "claude"+ )++ assert mutated == [], (+ "a skill whose extension restore source could not be read was "+ "not restored, so it must not be reported as mutated"+ )+ assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (+ "---\nname: speckit-fakeext-cmd\n---\n\ninstalled content\n"+ ), (+ "an unreadable extension source must leave the skill untouched β "+ "falling through to the rmtree branch would delete it exactly "+ "when its replacement cannot be generated"+ )++ def test_unregister_skills_in_dir_rejects_absolute_registry_name(+ self, project_dir+ ):+ """A corrupted ``registered_skills`` entry with an absolute path must not escape.++ ``Path`` join with an absolute right-hand operand discards the+ left side entirely (``skills_dir / "/abs/path"`` == ``"/abs/path"``),+ so an absolute in-project path stored in the registry would bypass+ ``skills_dir`` altogether if not rejected before the join (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ claude_skills_dir.mkdir(parents=True)++ precious_dir = project_dir / "important-data"+ precious_dir.mkdir()+ precious_file = precious_dir / "SKILL.md"+ precious_file.write_text("precious-absolute-target-marker")++ manager = PresetManager(project_dir)+ manager._unregister_skills_in_dir(+ [str(precious_dir)], claude_skills_dir, "claude"+ )++ assert precious_dir.is_dir(), (+ "an absolute registry entry must not let cleanup escape "+ "skills_dir to an unrelated project directory (#2948)"+ )+ assert precious_file.read_text() == "precious-absolute-target-marker"++ def test_infer_legacy_skill_provenance_rejects_absolute_registry_name(+ self, project_dir+ ):+ """Legacy provenance inference must reject an absolute registry name.++ ``_infer_legacy_skill_provenance`` receives its ``skill_names``+ directly from a legacy flat-list ``registered_skills`` value β+ registry data, not manifest-derived β and joins each name onto a+ candidate agent's resolved skills directory the same way+ ``_unregister_skills_in_dir`` does. An absolute in-project name+ discards the candidate directory entirely (Python's ``/`` operator+ drops the left side for an absolute right side), so it can read+ an unrelated project directory's ``SKILL.md`` and, if its+ frontmatter happens to carry a matching preset source marker,+ falsely attribute an unrelated directory as this preset's own+ skill override under whichever agent is being probed (#2948).+ """+ self._write_init_options(project_dir, ai="claude", ai_skills=True)+ claude_skills_dir = project_dir / ".claude" / "skills"+ claude_skills_dir.mkdir(parents=True)++ precious_dir = project_dir / "important-data"+ precious_dir.mkdir()+ (precious_dir / "SKILL.md").write_text(+ "---\n"+ "metadata:\n"+ " source: preset:some-pack\n"+ "---\n\n"+ "# Unrelated directory, not a real preset skill\n"+ )++ manager = PresetManager(project_dir)+ inferred = manager._infer_legacy_skill_provenance(+ [str(precious_dir)], "some-pack", "claude"+ )++ for names in inferred.values():+ assert str(precious_dir) not in names, (+ "an absolute registry entry must not be falsely attributed "+ "as preset-owned provenance by probing outside the "+ "intended skills subtree (#2948)"+ )+++class TestWrapStrategy:+ """Skill registration with inherited wrap metadata."""++ def test_register_skills_inherits_scripts_from_core_when_preset_omits_them(self, project_dir):+ """_register_skills merges scripts/agent_scripts from core when preset lacks them."""+ from specify_cli.presets import PresetManager+ import json++ # Core template with scripts+ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "wrap-test.md").write_text(+ "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh\n---\n\n"+ "Run: {SCRIPT}\n"+ )++ # Skills dir for claude+ skills_dir = project_dir / ".claude" / "skills"+ skills_dir.mkdir(parents=True, exist_ok=True)+ skill_subdir = skills_dir / "speckit-wrap-test"+ skill_subdir.mkdir()+ (skill_subdir / "SKILL.md").write_text("---\nname: speckit-wrap-test\n---\n\nold\n")++ (project_dir / ".specify" / "init-options.json").write_text(+ json.dumps({"ai": "claude", "ai_skills": True})+ )++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ written = (skill_subdir / "SKILL.md").read_text()+ # {SCRIPT} should have been resolved (not left as a literal placeholder)+ assert "{SCRIPT}" not in written++ def test_register_skills_preset_scripts_take_precedence_over_core(self, project_dir):+ """preset-defined scripts/agent_scripts are not overwritten by core frontmatter."""+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ core_dir = project_dir / ".specify" / "templates" / "commands"+ core_dir.mkdir(parents=True, exist_ok=True)+ (core_dir / "specify.md").write_text(+ "---\ndescription: core\nscripts:\n sh: core-run.sh\n---\n\nCore body.\n"+ )++ registrar = CommandRegistrar()+ body = "{CORE_TEMPLATE}"+ _, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)++ # Simulate preset frontmatter that already defines scripts+ preset_fm = {"description": "preset", "strategy": "wrap", "scripts": {"sh": "preset-run.sh"}}+ for key in ("scripts", "agent_scripts"):+ if key not in preset_fm and key in core_fm:+ preset_fm[key] = core_fm[key]++ # Preset's scripts must not be overwritten by core+ assert preset_fm["scripts"] == {"sh": "preset-run.sh"}diff --git a/tests/specify_cli/presets/test_manifest.py b/tests/specify_cli/presets/test_manifest.pynew file mode 100644index 000000000..27ac723da--- /dev/null+++ b/tests/specify_cli/presets/test_manifest.py@@ -0,0 +1,555 @@+"""Tests for preset manifest validation in specify_cli.presets._manifest."""++import pytest+import yaml++from specify_cli.presets import (+ VALID_PRESET_TEMPLATE_TYPES,+ PresetManifest,+ PresetValidationError,+)+++class TestPresetManifest:+ """Test PresetManifest validation and parsing."""++ def test_valid_manifest(self, pack_dir):+ """Test loading a valid manifest."""+ manifest = PresetManifest(pack_dir / "preset.yml")+ assert manifest.id == "test-pack"+ assert manifest.name == "Test Preset"+ assert manifest.version == "1.0.0"+ assert manifest.description == "A test preset"+ assert manifest.author == "Test Author"+ assert manifest.requires_speckit_version == ">=0.1.0"+ assert len(manifest.templates) == 1+ assert manifest.tags == ["testing", "example"]++ def test_missing_manifest(self, temp_dir):+ """Test that missing manifest raises error."""+ with pytest.raises(PresetValidationError, match="Manifest not found"):+ PresetManifest(temp_dir / "nonexistent.yml")++ def test_invalid_yaml(self, temp_dir):+ """Test that invalid YAML raises error."""+ bad_file = temp_dir / "bad.yml"+ bad_file.write_text(": invalid: yaml: {{{")+ with pytest.raises(PresetValidationError, match="Invalid YAML"):+ PresetManifest(bad_file)++ def test_utf8_non_ascii_description_loads(self, temp_dir, valid_pack_data):+ """Regression for #2325: non-ASCII (UTF-8) description loads on any platform.++ On Windows, Python's default text-mode encoding is the locale codepage+ (e.g. cp1252/GBK), which raises UnicodeDecodeError on UTF-8 bytes+ outside the ASCII range. The loader must open with encoding='utf-8'.+ """+ valid_pack_data["preset"]["description"] = "δΈζζ΅θ― β Γ©mojis π"+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_bytes(+ yaml.safe_dump(valid_pack_data, allow_unicode=True).encode("utf-8")+ )++ manifest = PresetManifest(manifest_path)+ assert manifest.description == "δΈζζ΅θ― β Γ©mojis π"++ def test_invalid_utf8_bytes_raises_validation_error(self, temp_dir):+ """Negative case: file containing invalid UTF-8 bytes raises PresetValidationError, not raw UnicodeDecodeError."""+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_bytes(b"\xff\xfe not valid utf-8 \xff\n")++ with pytest.raises(PresetValidationError, match="not valid UTF-8"):+ PresetManifest(manifest_path)++ def test_non_mapping_yaml_raises_validation_error(self, temp_dir):+ """Manifest whose YAML root is a scalar or list raises PresetValidationError, not TypeError."""+ manifest_path = temp_dir / "preset.yml"+ for bad_content in ("42\n", "[1, 2]\n"):+ manifest_path.write_text(bad_content, encoding="utf-8")+ with pytest.raises(PresetValidationError, match="YAML mapping"):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize("section", ["preset", "requires", "provides"])+ @pytest.mark.parametrize("bad_value", [None, [], "text"])+ def test_required_section_not_mapping_raises_validation_error(+ self, temp_dir, valid_pack_data, section, bad_value+ ):+ """Required manifest sections reject null, list, and scalar values."""+ valid_pack_data[section] = bad_value+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_text(+ yaml.safe_dump(valid_pack_data),+ encoding="utf-8",+ )++ with pytest.raises(+ PresetValidationError,+ match=rf"Invalid {section}: expected a mapping",+ ):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize("field", ["id", "name", "version", "description"])+ @pytest.mark.parametrize("bad", [1.0, 5, None, ["a"], {"a": 1}, True])+ def test_preset_metadata_field_not_string_raises_validation_error(+ self, temp_dir, valid_pack_data, field, bad+ ):+ """A non-string preset.<field> raises PresetValidationError, not a raw+ TypeError.++ The loop over these four fields only checked key PRESENCE, then fed the+ values to ``re.match`` (id) and ``packaging.Version`` (version), both of+ which raise a bare TypeError on a non-string. YAML makes that an easy+ authoring slip: unquoted ``version: 1.0`` parses as a float and ``id: 2``+ as an int. TypeError is not a PresetValidationError, so it escaped+ list_installed()'s "Corrupted preset" fallback and made+ `specify preset list` exit 1 with a raw traceback, hiding every healthy+ preset too. The sibling IntegrationDescriptor already type-checks the+ same four fields.+ """+ valid_pack_data["preset"][field] = bad+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_text(yaml.safe_dump(valid_pack_data), encoding="utf-8")++ with pytest.raises(+ PresetValidationError,+ match=rf"Invalid preset\.{field}: expected a string",+ ):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize("field", ["name", "file"])+ @pytest.mark.parametrize("bad", [1.0, 5, None, ["a"], {"a": 1}, True])+ def test_template_entry_field_not_string_raises_validation_error(+ self, temp_dir, valid_pack_data, field, bad+ ):+ """A non-string template ``name``/``file`` raises PresetValidationError.++ ``name`` reaches ``re.match`` and ``file`` reaches ``os.path.normpath``;+ both raise a bare TypeError on a non-string. The sibling extension+ manifest already rejects a non-string command ``file`` via+ relative_extension_path_violation().+ """+ valid_pack_data["provides"]["templates"][0][field] = bad+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_text(yaml.safe_dump(valid_pack_data), encoding="utf-8")++ with pytest.raises(+ PresetValidationError,+ match=rf"Invalid template {field}: expected a string",+ ):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize(+ "bad",+ [+ 5, "oops", {"a": 1}, # truthy non-lists+ 0, False, None, "", {}, # FALSY non-lists: must not fall through to+ # the misleading "at least one template"+ ],+ )+ def test_non_list_templates_raises_validation_error(+ self, temp_dir, valid_pack_data, bad+ ):+ """A non-list provides.templates raises the accurate type error, not a raw+ 'int object is not iterable' TypeError and not the misleading "must provide+ at least one template" (which a falsy non-list hit while the type check+ sat behind the emptiness check) β mirrors ExtensionManifest."""+ valid_pack_data["provides"]["templates"] = bad+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_text(yaml.dump(valid_pack_data), encoding="utf-8")+ with pytest.raises(PresetValidationError, match="templates.*expected a list"):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize("bad_entry", [None, 5, "oops", ["nested"]])+ def test_non_mapping_template_entry_raises_validation_error(+ self, temp_dir, valid_pack_data, bad_entry+ ):+ """A non-mapping template entry (null/scalar/list) raises PresetValidationError,+ not a raw 'argument of type ... is not iterable' TypeError from the+ `"type" not in tmpl` membership test β mirrors ExtensionManifest."""+ valid_pack_data["provides"]["templates"] = [bad_entry]+ manifest_path = temp_dir / "preset.yml"+ manifest_path.write_text(yaml.dump(valid_pack_data), encoding="utf-8")+ with pytest.raises(PresetValidationError, match="must be a mapping"):+ PresetManifest(manifest_path)++ def test_missing_schema_version(self, temp_dir, valid_pack_data):+ """Test missing schema_version field."""+ del valid_pack_data["schema_version"]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Missing required field: schema_version"):+ PresetManifest(manifest_path)++ def test_wrong_schema_version(self, temp_dir, valid_pack_data):+ """Test unsupported schema version."""+ valid_pack_data["schema_version"] = "2.0"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Unsupported schema version"):+ PresetManifest(manifest_path)++ def test_missing_pack_id(self, temp_dir, valid_pack_data):+ """Test missing preset.id field."""+ del valid_pack_data["preset"]["id"]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Missing preset.id"):+ PresetManifest(manifest_path)++ def test_invalid_pack_id_format(self, temp_dir, valid_pack_data):+ """Test invalid pack ID format."""+ valid_pack_data["preset"]["id"] = "Invalid_ID"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid preset ID"):+ PresetManifest(manifest_path)++ def test_invalid_version(self, temp_dir, valid_pack_data):+ """Test invalid semantic version."""+ valid_pack_data["preset"]["version"] = "not-a-version"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid version"):+ PresetManifest(manifest_path)++ def test_missing_speckit_version(self, temp_dir, valid_pack_data):+ """Test missing requires.speckit_version."""+ del valid_pack_data["requires"]["speckit_version"]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Missing requires.speckit_version"):+ PresetManifest(manifest_path)++ @pytest.mark.parametrize(+ "bad",+ [+ 1.0, # unquoted YAML float -- the likeliest authoring slip+ 5, # unquoted int+ True, # YAML `yes`/`true`+ None, # `speckit_version:` written but left empty+ [">=0.1.0"], # iterable: slips past SpecifierSet() entirely+ {"min": "0.1"}, # iterable: same+ " ", # blank string must not mean "any version"+ ],+ )+ def test_non_string_speckit_version(self, temp_dir, valid_pack_data, bad):+ """A non-string requires.speckit_version must be a PresetValidationError.++ It was presence-checked only, so it reached ``SpecifierSet(required)`` in+ check_compatibility(), which is guarded by ``except InvalidSpecifier``+ alone. A non-string escapes that guard two ways: scalars raise TypeError+ from the constructor, and a list/dict is iterable so SpecifierSet accepts+ it and the failure surfaces later as ``AttributeError: 'str' object has no+ attribute 'filter'`` from inside .contains().+ """+ valid_pack_data["requires"]["speckit_version"] = bad+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(+ PresetValidationError, match="Invalid requires.speckit_version"+ ):+ PresetManifest(manifest_path)++ def test_no_templates_provided(self, temp_dir, valid_pack_data):+ """Test pack with no templates."""+ valid_pack_data["provides"]["templates"] = []+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="must provide at least one template"):+ PresetManifest(manifest_path)++ def test_invalid_template_type(self, temp_dir, valid_pack_data):+ """Test template with invalid type."""+ valid_pack_data["provides"]["templates"][0]["type"] = "invalid"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid template type"):+ PresetManifest(manifest_path)++ def test_valid_template_types(self):+ """Test that all expected template types are valid."""+ assert "template" in VALID_PRESET_TEMPLATE_TYPES+ assert "command" in VALID_PRESET_TEMPLATE_TYPES+ assert "script" in VALID_PRESET_TEMPLATE_TYPES++ def test_template_missing_required_fields(self, temp_dir, valid_pack_data):+ """Test template missing required fields."""+ valid_pack_data["provides"]["templates"] = [{"type": "template"}]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="missing 'type', 'name', or 'file'"):+ PresetManifest(manifest_path)++ def test_invalid_template_name_format(self, temp_dir, valid_pack_data):+ """Test template with invalid name format."""+ valid_pack_data["provides"]["templates"][0]["name"] = "Invalid Name"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid template name"):+ PresetManifest(manifest_path)++ def test_get_hash(self, pack_dir):+ """Test manifest hash calculation."""+ manifest = PresetManifest(pack_dir / "preset.yml")+ hash_val = manifest.get_hash()+ assert hash_val.startswith("sha256:")+ import hashlib+ content = (pack_dir / "preset.yml").read_bytes()+ expected = f"sha256:{hashlib.sha256(content).hexdigest()}"+ assert hash_val == expected++ def test_multiple_templates(self, temp_dir, valid_pack_data):+ """Test pack with multiple templates of different types."""+ valid_pack_data["provides"]["templates"] = [+ {"type": "template", "name": "spec-template", "file": "templates/spec-template.md"},+ {"type": "template", "name": "plan-template", "file": "templates/plan-template.md"},+ {"type": "command", "name": "specify", "file": "commands/specify.md"},+ {"type": "script", "name": "create-new-feature", "file": "scripts/create-new-feature.sh"},+ ]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert len(manifest.templates) == 4++ def test_duplicate_template_name_and_type_raises_validation_error(+ self, temp_dir, valid_pack_data+ ):+ """A later entry with the same (name, type) pair must be rejected.++ ``PresetResolver._manifest_declared_template`` returns the FIRST+ 'provides.templates' entry matching a given (name, type) pair, so a+ later duplicate would be silently unreachable while still being+ counted by ``PresetManifest.templates`` -- mirroring the sibling bug+ fixed for ``ExtensionManifest``'s provides.templates/scripts (#4016).+ """+ valid_pack_data["provides"]["templates"] = [+ {"type": "command", "name": "specify", "file": "commands/specify-v1.md"},+ {"type": "command", "name": "specify", "file": "commands/specify-v2.md"},+ ]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Duplicate template name"):+ PresetManifest(manifest_path)++ def test_same_name_different_type_templates_allowed(+ self, temp_dir, valid_pack_data+ ):+ """The same name may recur across different template types."""+ valid_pack_data["provides"]["templates"] = [+ {"type": "template", "name": "specify", "file": "templates/specify.md"},+ {"type": "command", "name": "specify", "file": "commands/specify.md"},+ ]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert len(manifest.templates) == 2++ def test_requires_extensions_absent_is_valid(self, temp_dir, valid_pack_data):+ """A preset with no declared dependencies stays valid and reports none."""+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ assert PresetManifest(manifest_path).requires_extensions == []++ def test_requires_extensions_accepts_both_forms(self, temp_dir, valid_pack_data):+ """Bare ids and mappings normalize to the same shape."""+ valid_pack_data["requires"]["extensions"] = [+ "speckit-inventory",+ {"id": "other-ext", "version": ">=1.2.0", "required": False},+ ]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)++ assert PresetManifest(manifest_path).requires_extensions == [+ {"id": "speckit-inventory", "version": None, "required": True},+ {"id": "other-ext", "version": ">=1.2.0", "required": False},+ ]++ @pytest.mark.parametrize(+ "bad, expected",+ [+ ("speckit-inventory", "Invalid requires.extensions"), # str, not list+ ({"id": "x"}, "Invalid requires.extensions"), # mapping, not list+ ([123], r"Invalid requires\.extensions\[0\]"), # member not str/mapping+ ([None], r"Invalid requires\.extensions\[0\]"),+ ([{"version": ">=1"}], r"Missing requires\.extensions\[0\]\.id"),+ ([{"id": 5}], r"Invalid requires\.extensions\[0\]\.id"),+ ([{"id": "Bad_ID"}], r"Invalid requires\.extensions\[0\]\.id"),+ (["Bad_ID"], r"Invalid requires\.extensions\[0\]\.id"),+ ([{"id": "x", "version": 1.0}], r"Invalid requires\.extensions\[0\]\.version"),+ ([{"id": "x", "version": " "}], r"Invalid requires\.extensions\[0\]\.version"),+ ([{"id": "x", "version": "nonsense"}], r"Invalid requires\.extensions\[0\]\.version"),+ ([{"id": "x", "required": "yes"}], r"Invalid requires\.extensions\[0\]\.required"),+ # `$` also matches before a trailing newline, so an anchored+ # re.match would admit these while the resolver's fullmatch-based+ # safe-id check rejects them.+ (["demo-ext\n"], r"Invalid requires\.extensions\[0\]\.id"),+ ([{"id": "demo-ext\n"}], r"Invalid requires\.extensions\[0\]\.id"),+ (["demo\next"], r"Invalid requires\.extensions\[0\]\.id"),+ ],+ )+ def test_requires_extensions_rejects_malformed(+ self, temp_dir, valid_pack_data, bad, expected+ ):+ """Malformed dependency declarations fail as PresetValidationError.++ Same reasoning as requires.speckit_version: an unvalidated value reaches+ ``SpecifierSet`` or ``re.match`` later and surfaces as a bare TypeError+ that no caller handles as a malformed manifest.+ """+ valid_pack_data["requires"]["extensions"] = bad+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match=expected):+ PresetManifest(manifest_path)+++class TestCompositionStrategyValidation:+ """Test strategy field validation in PresetManifest."""++ def test_valid_replace_strategy(self, temp_dir, valid_pack_data):+ """Test that replace strategy is accepted."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "replace"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "replace"++ def test_valid_prepend_strategy(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "prepend"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "prepend"++ def test_valid_append_strategy(self, temp_dir, valid_pack_data):+ """Test that append strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "append"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "append"++ def test_valid_wrap_strategy(self, temp_dir, valid_pack_data):+ """Test that wrap strategy is accepted for templates."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "wrap"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ (temp_dir / "templates").mkdir(exist_ok=True)+ (temp_dir / "templates" / "spec-template.md").write_text("test")+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "wrap"++ def test_default_strategy_is_replace(self, pack_dir):+ """Test that omitting strategy defaults to replace (key is absent)."""+ manifest = PresetManifest(pack_dir / "preset.yml")+ # Strategy key should not be present in the manifest data+ assert "strategy" not in manifest.templates[0]+ # But consumers should treat missing strategy as "replace"+ assert manifest.templates[0].get("strategy", "replace") == "replace"++ def test_invalid_strategy_rejected(self, temp_dir, valid_pack_data):+ """Test that invalid strategy values are rejected."""+ valid_pack_data["provides"]["templates"][0]["strategy"] = "merge"+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy"):+ PresetManifest(manifest_path)++ def test_prepend_rejected_for_scripts(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is rejected for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "prepend",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):+ PresetManifest(manifest_path)++ def test_append_rejected_for_scripts(self, temp_dir, valid_pack_data):+ """Test that append strategy is rejected for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "append",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):+ PresetManifest(manifest_path)++ def test_wrap_accepted_for_scripts(self, temp_dir, valid_pack_data):+ """Test that wrap strategy is accepted for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "wrap",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "wrap"++ def test_replace_accepted_for_scripts(self, temp_dir, valid_pack_data):+ """Test that replace strategy is accepted for scripts."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "script",+ "name": "create-new-feature",+ "file": "scripts/create-new-feature.sh",+ "strategy": "replace",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "replace"++ def test_prepend_accepted_for_commands(self, temp_dir, valid_pack_data):+ """Test that prepend strategy is accepted for commands."""+ valid_pack_data["provides"]["templates"] = [{+ "type": "command",+ "name": "speckit.specify",+ "file": "commands/speckit.specify.md",+ "strategy": "prepend",+ }]+ manifest_path = temp_dir / "preset.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_pack_data, f)+ manifest = PresetManifest(manifest_path)+ assert manifest.templates[0]["strategy"] == "prepend"diff --git a/tests/specify_cli/presets/test_registry.py b/tests/specify_cli/presets/test_registry.pynew file mode 100644index 000000000..07ae8ca8f--- /dev/null+++ b/tests/specify_cli/presets/test_registry.py@@ -0,0 +1,396 @@+"""Tests for preset registry persistence and priority in specify_cli.presets._registry."""++import pytest++from specify_cli.presets import PresetRegistry+++class TestPresetRegistry:+ """Test PresetRegistry operations."""++ def test_empty_registry(self, temp_dir):+ """Test empty registry initialization."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)+ assert registry.list() == {}+ assert not registry.is_installed("test-pack")++ def test_load_starts_fresh_for_non_utf8_registry(self, temp_dir):+ """A registry file with undecodable bytes must start fresh, not raise.++ ``_load()`` already treats malformed JSON as "corrupted registry,+ start fresh", but a registry whose *bytes* cannot be decoded as UTF-8+ raised a raw ``UnicodeDecodeError`` from the same boundary β the same+ corruption class reaching a different exception type.+ """+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ (packs_dir / PresetRegistry.REGISTRY_FILE).write_bytes(+ b"\xff\xfe not utf-8 \xc3\x28"+ )++ registry = PresetRegistry(packs_dir)++ assert registry.data == {+ "schema_version": PresetRegistry.SCHEMA_VERSION,+ "presets": {},+ }++ def test_add_and_get(self, temp_dir):+ """Test adding and retrieving a pack."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("test-pack", {"version": "1.0.0", "source": "local"})+ assert registry.is_installed("test-pack")++ metadata = registry.get("test-pack")+ assert metadata is not None+ assert metadata["version"] == "1.0.0"+ assert "installed_at" in metadata++ def test_remove(self, temp_dir):+ """Test removing a pack."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("test-pack", {"version": "1.0.0"})+ assert registry.is_installed("test-pack")++ registry.remove("test-pack")+ assert not registry.is_installed("test-pack")++ def test_remove_nonexistent(self, temp_dir):+ """Test removing a pack that doesn't exist."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)+ registry.remove("nonexistent") # Should not raise++ def test_list(self, temp_dir):+ """Test listing all packs."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-a", {"version": "1.0.0"})+ registry.add("pack-b", {"version": "2.0.0"})++ all_packs = registry.list()+ assert len(all_packs) == 2+ assert "pack-a" in all_packs+ assert "pack-b" in all_packs++ def test_persistence(self, temp_dir):+ """Test that registry data persists across instances."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()++ # Add with first instance+ registry1 = PresetRegistry(packs_dir)+ registry1.add("test-pack", {"version": "1.0.0"})++ # Load with second instance+ registry2 = PresetRegistry(packs_dir)+ assert registry2.is_installed("test-pack")++ def test_corrupted_registry(self, temp_dir):+ """Test recovery from corrupted registry file."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()++ registry_file = packs_dir / ".registry"+ registry_file.write_text("not valid json{{{")++ registry = PresetRegistry(packs_dir)+ assert registry.list() == {}++ def test_get_nonexistent(self, temp_dir):+ """Test getting a nonexistent pack."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)+ assert registry.get("nonexistent") is None++ def test_restore(self, temp_dir):+ """Test restore() preserves timestamps exactly."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ # Create original entry with a specific timestamp+ original_metadata = {+ "version": "1.0.0",+ "source": "local",+ "installed_at": "2025-01-15T10:30:00+00:00",+ "enabled": True,+ }+ registry.restore("test-pack", original_metadata)++ # Verify exact restoration+ restored = registry.get("test-pack")+ assert restored["installed_at"] == "2025-01-15T10:30:00+00:00"+ assert restored["version"] == "1.0.0"+ assert restored["enabled"] is True++ def test_restore_rejects_none_metadata(self, temp_dir):+ """Test restore() raises ValueError for None metadata."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ with pytest.raises(ValueError, match="metadata must be a dict"):+ registry.restore("test-pack", None)++ def test_restore_rejects_non_dict_metadata(self, temp_dir):+ """Test restore() raises ValueError for non-dict metadata."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ with pytest.raises(ValueError, match="metadata must be a dict"):+ registry.restore("test-pack", "not-a-dict")++ with pytest.raises(ValueError, match="metadata must be a dict"):+ registry.restore("test-pack", ["list", "not", "dict"])++ def test_restore_uses_deep_copy(self, temp_dir):+ """Test restore() deep copies metadata to prevent mutation."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ original_metadata = {+ "version": "1.0.0",+ "nested": {"key": "original"},+ }+ registry.restore("test-pack", original_metadata)++ # Mutate the original metadata after restore+ original_metadata["version"] = "MUTATED"+ original_metadata["nested"]["key"] = "MUTATED"++ # Registry should have the original values+ stored = registry.get("test-pack")+ assert stored["version"] == "1.0.0"+ assert stored["nested"]["key"] == "original"++ def test_get_returns_deep_copy(self, temp_dir):+ """Test that get() returns a deep copy to prevent mutation."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("test-pack", {"version": "1.0.0", "nested": {"key": "original"}})++ # Get and mutate the returned copy+ metadata = registry.get("test-pack")+ metadata["version"] = "MUTATED"+ metadata["nested"]["key"] = "MUTATED"++ # Original should be unchanged+ fresh = registry.get("test-pack")+ assert fresh["version"] == "1.0.0"+ assert fresh["nested"]["key"] == "original"++ def test_get_returns_none_for_corrupted_entry(self, temp_dir):+ """Test that get() returns None for corrupted (non-dict) entries."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ # Directly corrupt the registry with non-dict entries+ registry.data["presets"]["corrupted-string"] = "not a dict"+ registry.data["presets"]["corrupted-list"] = ["not", "a", "dict"]+ registry.data["presets"]["corrupted-int"] = 42+ registry._save()++ # All corrupted entries should return None+ assert registry.get("corrupted-string") is None+ assert registry.get("corrupted-list") is None+ assert registry.get("corrupted-int") is None+ # Non-existent should also return None+ assert registry.get("nonexistent") is None++ def test_list_returns_deep_copy(self, temp_dir):+ """Test that list() returns deep copies to prevent mutation."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("test-pack", {"version": "1.0.0", "nested": {"key": "original"}})++ # Get list and mutate+ all_packs = registry.list()+ all_packs["test-pack"]["version"] = "MUTATED"+ all_packs["test-pack"]["nested"]["key"] = "MUTATED"++ # Original should be unchanged+ fresh = registry.get("test-pack")+ assert fresh["version"] == "1.0.0"+ assert fresh["nested"]["key"] == "original"++ def test_list_returns_empty_dict_for_corrupted_registry(self, temp_dir):+ """Test that list() returns empty dict when presets is not a dict."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ # Corrupt the registry - presets is a list instead of dict+ registry.data["presets"] = ["not", "a", "dict"]+ registry._save()++ # list() should return empty dict, not crash+ result = registry.list()+ assert result == {}++ def test_list_by_priority_excludes_disabled(self, temp_dir):+ """Test that list_by_priority excludes disabled presets by default."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-enabled", {"version": "1.0.0", "enabled": True, "priority": 5})+ registry.add("pack-disabled", {"version": "1.0.0", "enabled": False, "priority": 1})+ registry.add("pack-default", {"version": "1.0.0", "priority": 10}) # no enabled field = True++ # Default: exclude disabled+ by_priority = registry.list_by_priority()+ pack_ids = [p[0] for p in by_priority]+ assert "pack-enabled" in pack_ids+ assert "pack-default" in pack_ids+ assert "pack-disabled" not in pack_ids++ def test_list_by_priority_includes_disabled_when_requested(self, temp_dir):+ """Test that list_by_priority includes disabled presets when requested."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-enabled", {"version": "1.0.0", "enabled": True, "priority": 5})+ registry.add("pack-disabled", {"version": "1.0.0", "enabled": False, "priority": 1})++ # Include disabled+ by_priority = registry.list_by_priority(include_disabled=True)+ pack_ids = [p[0] for p in by_priority]+ assert "pack-enabled" in pack_ids+ assert "pack-disabled" in pack_ids+ # Disabled pack has lower priority number, so it comes first when included+ assert pack_ids[0] == "pack-disabled"+++class TestRegistryPriority:+ """Test registry priority sorting."""++ def test_list_by_priority(self, temp_dir):+ """Test that list_by_priority sorts by priority number."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-high", {"version": "1.0.0", "priority": 1})+ registry.add("pack-low", {"version": "1.0.0", "priority": 20})+ registry.add("pack-mid", {"version": "1.0.0", "priority": 10})++ sorted_packs = registry.list_by_priority()+ assert len(sorted_packs) == 3+ assert sorted_packs[0][0] == "pack-high"+ assert sorted_packs[1][0] == "pack-mid"+ assert sorted_packs[2][0] == "pack-low"++ def test_list_by_priority_default(self, temp_dir):+ """Test that packs without priority default to 10."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-a", {"version": "1.0.0"}) # no priority, defaults to 10+ registry.add("pack-b", {"version": "1.0.0", "priority": 5})++ sorted_packs = registry.list_by_priority()+ assert sorted_packs[0][0] == "pack-b"+ assert sorted_packs[1][0] == "pack-a"++ def test_list_by_priority_invalid_priority_defaults(self, temp_dir):+ """Malformed priority values fall back to the default priority."""+ packs_dir = temp_dir / "packs"+ packs_dir.mkdir()+ registry = PresetRegistry(packs_dir)++ registry.add("pack-high", {"version": "1.0.0", "priority": 1})+ registry.data["presets"]["pack-invalid"] = {+ "version": "1.0.0",+ "priority": "high",+ }+ registry._save()++ sorted_packs = registry.list_by_priority()++ assert [item[0] for item in sorted_packs] == ["pack-high", "pack-invalid"]+ assert sorted_packs[1][1]["priority"] == 10+++class TestPresetPriorityBackwardsCompatibility:+ """Test backwards compatibility for presets installed before priority feature."""++ def test_legacy_preset_without_priority_field(self, temp_dir):+ """Presets installed before priority feature should default to 10."""+ presets_dir = temp_dir / ".specify" / "presets"+ presets_dir.mkdir(parents=True)++ # Simulate legacy registry entry without priority field+ registry = PresetRegistry(presets_dir)+ registry.data["presets"]["legacy-pack"] = {+ "version": "1.0.0",+ "source": "local",+ "enabled": True,+ "installed_at": "2025-01-01T00:00:00Z",+ # No "priority" field - simulates pre-feature preset+ }+ registry._save()++ # Reload registry+ registry2 = PresetRegistry(presets_dir)++ # list_by_priority should use default of 10+ result = registry2.list_by_priority()+ assert len(result) == 1+ assert result[0][0] == "legacy-pack"+ # Priority defaults to 10 and is normalized in returned metadata+ assert result[0][1]["priority"] == 10++ def test_mixed_legacy_and_new_presets_ordering(self, temp_dir):+ """Legacy presets (no priority) sort with default=10 among prioritized presets."""+ presets_dir = temp_dir / ".specify" / "presets"+ presets_dir.mkdir(parents=True)++ registry = PresetRegistry(presets_dir)++ # Add preset with explicit priority=5+ registry.add("pack-with-priority", {"version": "1.0.0", "priority": 5})++ # Add legacy preset without priority (manually)+ registry.data["presets"]["legacy-pack"] = {+ "version": "1.0.0",+ "source": "local",+ "enabled": True,+ # No priority field+ }++ # Add another preset with priority=15+ registry.add("low-priority-pack", {"version": "1.0.0", "priority": 15})+ registry._save()++ # Reload and check ordering+ registry2 = PresetRegistry(presets_dir)+ sorted_presets = registry2.list_by_priority()++ # Should be: pack-with-priority (5), legacy-pack (default 10), low-priority-pack (15)+ assert [p[0] for p in sorted_presets] == [+ "pack-with-priority",+ "legacy-pack",+ "low-priority-pack",+ ]diff --git a/tests/specify_cli/presets/test_resolver.py b/tests/specify_cli/presets/test_resolver.pynew file mode 100644index 000000000..d1e416f7a--- /dev/null+++ b/tests/specify_cli/presets/test_resolver.py@@ -0,0 +1,1802 @@+"""Tests for preset layer resolution and composition in specify_cli.presets._resolver."""++import json+from pathlib import Path++import pytest+import yaml++from specify_cli.extensions import ExtensionRegistry+from specify_cli.presets import (+ PresetManager,+ PresetRegistry,+ PresetResolver,+ PresetValidationError,+)+from tests.specify_cli.presets._helpers import (+ CORE_TEMPLATE_NAMES,+ install_self_test_preset,+)+++class TestPresetResolver:+ """Test PresetResolver priority stack."""++ def test_resolve_core_template(self, project_dir):+ """Test resolving a core template."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert result.name == "spec-template.md"+ assert "Core Spec Template" in result.read_text()++ def test_resolve_nonexistent(self, project_dir):+ """Test resolving a nonexistent template returns None."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("nonexistent-template")+ assert result is None++ def test_resolver_ignores_traversing_registry_ids(self, project_dir):+ """Registry IDs cannot escape preset or extension install roots."""+ for registry_dir, registry_key, outside_name in (+ ("presets", "presets", "outside-preset"),+ ("extensions", "extensions", "outside-extension"),+ ):+ outside = project_dir.parent / outside_name+ (outside / "templates").mkdir(parents=True)+ (outside / "templates" / "spec-template.md").write_text(+ f"# Sensitive {registry_key}\n",+ encoding="utf-8",+ )+ installed = project_dir / ".specify" / registry_dir+ installed.mkdir(parents=True, exist_ok=True)+ (installed / ".registry").write_text(+ json.dumps(+ {+ registry_key: {+ f"../../../{outside_name}": {+ "enabled": True,+ "priority": 1,+ }+ }+ }+ ),+ encoding="utf-8",+ )++ content = PresetResolver(project_dir).resolve_content("spec-template")++ assert content is not None+ assert "Core Spec Template" in content+ assert "Sensitive" not in content++ def test_resolve_higher_priority_pack_wins(self, project_dir, temp_dir, valid_pack_data):+ """Test that a pack with lower priority number wins over higher number."""+ manager = PresetManager(project_dir)++ # Create pack A (priority 10 β lower precedence)+ pack_a_dir = temp_dir / "pack-a"+ pack_a_dir.mkdir()+ data_a = {**valid_pack_data}+ data_a["preset"] = {**valid_pack_data["preset"], "id": "pack-a", "name": "Pack A"}+ with open(pack_a_dir / "preset.yml", 'w') as f:+ yaml.dump(data_a, f)+ (pack_a_dir / "templates").mkdir()+ (pack_a_dir / "templates" / "spec-template.md").write_text("# From Pack A\n")++ # Create pack B (priority 1 β higher precedence)+ pack_b_dir = temp_dir / "pack-b"+ pack_b_dir.mkdir()+ data_b = {**valid_pack_data}+ data_b["preset"] = {**valid_pack_data["preset"], "id": "pack-b", "name": "Pack B"}+ with open(pack_b_dir / "preset.yml", 'w') as f:+ yaml.dump(data_b, f)+ (pack_b_dir / "templates").mkdir()+ (pack_b_dir / "templates" / "spec-template.md").write_text("# From Pack B\n")++ # Install A first (priority 10), B second (priority 1)+ manager.install_from_directory(pack_a_dir, "0.1.5", priority=10)+ manager.install_from_directory(pack_b_dir, "0.1.5", priority=1)++ # Pack B should win because lower priority number+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "From Pack B" in result.read_text()++ def test_resolve_override_takes_priority(self, project_dir):+ """Test that project overrides take priority over core."""+ # Create override+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ override = overrides_dir / "spec-template.md"+ override.write_text("# Override Spec Template\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Override Spec Template" in result.read_text()++ def test_resolve_pack_takes_priority_over_core(self, project_dir, pack_dir):+ """Test that installed packs take priority over core templates."""+ # Install the pack+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Custom Spec Template" in result.read_text()++ def _install_pack_with_manifest_file(self, project_dir, *, extra_file=False):+ """Create a pack whose manifest declares a NON-convention file: path.++ Returns the pack dir under the project. The declared file lives at+ custom/spec.md (not the convention templates/spec-template.md).+ """+ presets_dir = project_dir / ".specify" / "presets"+ pack_dir = presets_dir / "mypack"+ (pack_dir / "custom").mkdir(parents=True)+ (pack_dir / "custom" / "spec.md").write_text(+ "# Manifest-declared Spec\n", encoding="utf-8"+ )+ if extra_file:+ # An undeclared convention-path file the manifest points away from.+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text(+ "# Stray Convention Spec\n", encoding="utf-8"+ )+ manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "mypack",+ "name": "My Pack",+ "version": "1.0.0",+ "description": "declares a non-convention file path",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "spec-template",+ "file": "custom/spec.md",+ "strategy": "replace",+ }+ ]+ },+ }+ with open(pack_dir / "preset.yml", "w") as f:+ yaml.dump(manifest, f)+ PresetRegistry(presets_dir).add(+ "mypack", {"version": "1.0.0", "priority": 10}+ )+ return pack_dir++ def test_resolve_uses_manifest_declared_file_path(self, project_dir):+ """resolve() must honor a manifest-declared non-convention file: path.++ Previously the tier-2 loop was convention-only, so it returned the+ core template and resolve_with_source() misattributed source='core',+ diverging from collect_all_layers()/resolve_content().+ """+ pack_dir = self._install_pack_with_manifest_file(project_dir)+ resolver = PresetResolver(project_dir)++ result = resolver.resolve("spec-template")+ assert result == pack_dir / "custom" / "spec.md"+ assert "Manifest-declared Spec" in result.read_text()++ sourced = resolver.resolve_with_source("spec-template")+ assert sourced is not None+ assert "mypack" in sourced["source"]+ # resolve() must agree with collect_all_layers()'s top layer.+ layers = resolver.collect_all_layers("spec-template")+ assert Path(layers[0]["path"]) == pack_dir / "custom" / "spec.md"++ def test_resolve_manifest_file_wins_over_undeclared_convention_file(+ self, project_dir+ ):+ """A stray convention-path file must not shadow the manifest's file:."""+ pack_dir = self._install_pack_with_manifest_file(+ project_dir, extra_file=True+ )+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result == pack_dir / "custom" / "spec.md"+ assert "Manifest-declared Spec" in result.read_text()++ def test_resolve_skips_convention_when_manifest_file_missing(self, project_dir):+ """When the manifest declares a file: that does not exist, resolve()+ must NOT fall back to a convention file in the same pack (that would+ mask a typo) β it skips the pack and resolves core instead."""+ presets_dir = project_dir / ".specify" / "presets"+ pack_dir = presets_dir / "mypack"+ # Manifest declares custom/spec.md (MISSING); a convention file exists+ # in the pack and must NOT be used.+ (pack_dir / "templates").mkdir(parents=True)+ (pack_dir / "templates" / "spec-template.md").write_text(+ "# Stray Convention Spec\n", encoding="utf-8"+ )+ manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "mypack",+ "name": "My Pack",+ "version": "1.0.0",+ "description": "declares a missing file path",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "spec-template",+ "file": "custom/spec.md",+ "strategy": "replace",+ }+ ]+ },+ }+ with open(pack_dir / "preset.yml", "w") as f:+ yaml.dump(manifest, f)+ PresetRegistry(presets_dir).add(+ "mypack", {"version": "1.0.0", "priority": 10}+ )++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ content = result.read_text()+ assert "Stray Convention Spec" not in content # pack convention skipped+ assert "Core Spec Template" in content # fell through to core++ def test_resolve_skips_convention_when_manifest_file_is_directory(+ self, project_dir+ ):+ """When the manifest's file: path resolves to a DIRECTORY (not a regular+ file), resolve()/collect_all_layers() must treat it as missing β exists()+ would accept it and downstream read_text() on a directory would crash.+ The pack is skipped (no convention fallback), so core wins."""+ presets_dir = project_dir / ".specify" / "presets"+ pack_dir = presets_dir / "mypack"+ # Declared file: custom/spec.md is created as a DIRECTORY.+ (pack_dir / "custom" / "spec.md").mkdir(parents=True)+ # A convention file also exists and must NOT be used.+ (pack_dir / "templates").mkdir(parents=True)+ (pack_dir / "templates" / "spec-template.md").write_text(+ "# Stray Convention Spec\n", encoding="utf-8"+ )+ manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": "mypack",+ "name": "My Pack",+ "version": "1.0.0",+ "description": "declares a file: that is actually a directory",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "template",+ "name": "spec-template",+ "file": "custom/spec.md",+ "strategy": "replace",+ }+ ]+ },+ }+ with open(pack_dir / "preset.yml", "w") as f:+ yaml.dump(manifest, f)+ PresetRegistry(presets_dir).add(+ "mypack", {"version": "1.0.0", "priority": 10}+ )++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert result.is_file() # never a directory+ content = result.read_text()+ assert "Stray Convention Spec" not in content # pack convention skipped+ assert "Core Spec Template" in content # fell through to core+ # collect_all_layers() must agree: the directory is not a layer.+ layers = resolver.collect_all_layers("spec-template")+ assert all(Path(layer["path"]).is_file() for layer in layers)+ assert all(+ Path(layer["path"]) != pack_dir / "custom" / "spec.md"+ for layer in layers+ )++ def test_resolve_override_takes_priority_over_pack(self, project_dir, pack_dir):+ """Test that overrides take priority over installed packs."""+ # Install the pack+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ # Create override+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ override = overrides_dir / "spec-template.md"+ override.write_text("# Override Spec Template\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Override Spec Template" in result.read_text()++ def test_resolve_extension_provided_templates(self, project_dir):+ """Test resolving templates provided by extensions."""+ # Create extension with templates+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "custom-template.md"+ ext_template.write_text("# Extension Custom Template\n")++ # Register extension in registry+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("custom-template")+ assert result is not None+ assert "Extension Custom Template" in result.read_text()++ def test_resolve_disabled_extension_templates_skipped(self, project_dir):+ """Test that disabled extension templates are not resolved."""+ # Create extension with templates+ ext_dir = project_dir / ".specify" / "extensions" / "disabled-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "disabled-template.md"+ ext_template.write_text("# Disabled Extension Template\n")++ # Register extension as disabled+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("disabled-ext", {"version": "1.0.0", "priority": 1, "enabled": False})++ # Template should NOT be resolved because extension is disabled+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("disabled-template")+ assert result is None, "Disabled extension template should not be resolved"++ def test_resolve_disabled_extension_not_picked_up_as_unregistered(self, project_dir):+ """Test that disabled extensions are not picked up via unregistered dir scan."""+ # Create extension directory with templates+ ext_dir = project_dir / ".specify" / "extensions" / "test-disabled-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "unique-disabled-template.md"+ ext_template.write_text("# Should Not Resolve\n")++ # Register the extension but disable it+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("test-disabled-ext", {"version": "1.0.0", "enabled": False})++ # Verify the template is NOT resolved (even though the directory exists)+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("unique-disabled-template")+ assert result is None, "Disabled extension should not be picked up as unregistered"++ @pytest.mark.parametrize(+ "registry_bytes",+ [b"{ not valid json", b'{"extensions": []}', b"[]"],+ ids=["invalid_json", "non_mapping_extensions", "non_mapping_root"],+ )+ def test_resolve_fails_closed_on_corrupt_extension_registry(+ self, project_dir, registry_bytes+ ):+ """A corrupt extension registry must fail closed rather than let the+ directory scan admit every on-disk extension as enabled."""+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"+ ext_templates_dir.mkdir(parents=True)+ (ext_templates_dir / "custom-template.md").write_text(+ "# Should not be served\n"+ )+ (extensions_dir / ".registry").write_bytes(registry_bytes)++ resolver = PresetResolver(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid extension registry"):+ resolver._get_all_extensions_by_priority()+ with pytest.raises(PresetValidationError, match="Invalid extension registry"):+ resolver.resolve("custom-template")++ def test_resolve_fails_closed_when_registry_is_directory(self, project_dir):+ """A directory at the registry path must fail closed, not be treated as+ an absent registry that enables every on-disk extension."""+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"+ ext_templates_dir.mkdir(parents=True)+ (ext_templates_dir / "custom-template.md").write_text(+ "# Should not be served\n"+ )+ (extensions_dir / ".registry").mkdir()++ resolver = PresetResolver(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid extension registry"):+ resolver.resolve("custom-template")++ def test_resolve_fails_closed_when_registry_is_broken_symlink(self, project_dir):+ """A dangling ``.registry`` symlink must fail closed. ``Path.exists()``+ follows symlinks and would mistake it for an absent registry, reopening+ the fail-open directory scan."""+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"+ ext_templates_dir.mkdir(parents=True)+ (ext_templates_dir / "custom-template.md").write_text(+ "# Should not be served\n"+ )+ (extensions_dir / ".registry").symlink_to(+ extensions_dir / "does-not-exist"+ )++ registry = ExtensionRegistry(extensions_dir)+ assert registry.is_corrupt()+ resolver = PresetResolver(project_dir)+ with pytest.raises(PresetValidationError, match="Invalid extension registry"):+ resolver.resolve("custom-template")++ def test_resolve_pack_over_extension(self, project_dir, pack_dir, temp_dir, valid_pack_data):+ """Test that pack templates take priority over extension templates."""+ # Create extension with templates+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "spec-template.md"+ ext_template.write_text("# Extension Spec Template\n")++ # Install a pack with the same template+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ # Pack should win over extension+ assert "Custom Spec Template" in result.read_text()++ def test_resolve_with_source_core(self, project_dir):+ """Test resolve_with_source for core template."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("spec-template")+ assert result is not None+ assert result["source"] == "core"+ assert "spec-template.md" in result["path"]++ def test_resolve_with_source_override(self, project_dir):+ """Test resolve_with_source for override template."""+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ override = overrides_dir / "spec-template.md"+ override.write_text("# Override\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("spec-template")+ assert result is not None+ assert result["source"] == "project override"++ def test_resolve_with_source_pack(self, project_dir, pack_dir):+ """Test resolve_with_source for pack template."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("spec-template")+ assert result is not None+ assert "test-pack" in result["source"]+ assert "v1.0.0" in result["source"]++ def test_resolve_with_source_extension(self, project_dir):+ """Test resolve_with_source for extension-provided template."""+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "unique-template.md"+ ext_template.write_text("# Unique\n")++ # Register extension in registry+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("unique-template")+ assert result is not None+ assert result["source"] == "extension:my-ext v1.0.0"++ def test_resolve_with_source_not_found(self, project_dir):+ """Test resolve_with_source for nonexistent template."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("nonexistent")+ assert result is None++ def test_resolve_skips_hidden_extension_dirs(self, project_dir):+ """Test that hidden directories in extensions are skipped."""+ ext_dir = project_dir / ".specify" / "extensions" / ".backup"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ ext_template = ext_templates_dir / "hidden-template.md"+ ext_template.write_text("# Hidden\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("hidden-template")+ assert result is None++ def test_collect_all_layers_finds_bundled_core_without_specify_commands(+ self, project_dir+ ):+ """Tier-5 fallback locates the bundled core command when+ .specify/templates/commands/ has no matching file.++ Regression test for #3086: a stale ``.parent`` chain made the+ source-checkout fallback resolve to ``src/templates/...`` (which does+ not exist), so ``wrap`` presets found no base layer. The fallback must+ resolve against the real repo-root ``templates/commands`` tree.+ """+ # project_dir's commands dir is empty, so tier-4 cannot satisfy this.+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("speckit.implement", "command")+ assert layers, "expected a bundled core base layer to be found"+ assert layers[-1]["source"] == "core (bundled)"+ assert layers[-1]["path"].parts[-2:] == ("commands", "implement.md")++ def test_resolve_command_falls_back_to_bundled_core(self, project_dir):+ """resolve() tier-5 returns the bundled core command when+ .specify/templates/commands/ lacks it (regression for #3086)."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("speckit.implement", "command")+ assert result is not None+ assert result.parts[-2:] == ("commands", "implement.md")+++class TestResolveCore:+ """Test PresetResolver.resolve_core() skips the installed-presets tier."""++ def test_resolve_core_does_not_return_preset_files(self, project_dir):+ """resolve_core must not return files from .specify/presets/."""+ preset_cmd_dir = project_dir / ".specify" / "presets" / "my-preset" / "commands"+ preset_cmd_dir.mkdir(parents=True)+ (preset_cmd_dir / "specify.md").write_text("---\ndescription: preset wrap\n---\n\nwrap body\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_core("specify", "command")+ # The preset file must never be returned β but the bundled core may be.+ if result is not None:+ assert "presets" not in result.parts++ def test_resolve_core_returns_core_template(self, project_dir):+ """resolve_core falls through to core templates (tier 4)."""+ core_cmd_dir = project_dir / ".specify" / "templates" / "commands"+ core_cmd_dir.mkdir(parents=True, exist_ok=True)+ (core_cmd_dir / "specify.md").write_text("---\ndescription: core\n---\n\ncore body\n")++ # Also place a preset file β resolve_core must still return the core+ preset_cmd_dir = project_dir / ".specify" / "presets" / "my-preset" / "commands"+ preset_cmd_dir.mkdir(parents=True)+ (preset_cmd_dir / "specify.md").write_text("---\ndescription: preset wrap\n---\n\nwrap body\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_core("specify", "command")+ assert result is not None+ assert "presets" not in result.parts+ assert result.parts[-3:] == ("templates", "commands", "specify.md")++ def test_resolve_core_returns_override(self, project_dir):+ """resolve_core returns tier-1 override if present."""+ override_dir = project_dir / ".specify" / "templates" / "overrides"+ override_dir.mkdir(parents=True)+ (override_dir / "specify.md").write_text("---\ndescription: override\n---\n\noverride body\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_core("specify", "command")+ assert result is not None+ assert result.parts[-2:] == ("overrides", "specify.md")++ def test_resolve_core_returns_extension_template(self, project_dir):+ """resolve_core returns extension templates (tier 3)."""+ ext_cmd_dir = project_dir / ".specify" / "extensions" / "myext" / "commands"+ ext_cmd_dir.mkdir(parents=True)+ (ext_cmd_dir / "myext-cmd.md").write_text("---\ndescription: ext\n---\n\next body\n")++ resolver = PresetResolver(project_dir)+ result = resolver.resolve_core("myext-cmd", "command")+ assert result is not None+ assert result.parts[-4:-1] == ("extensions", "myext", "commands")++ def test_resolve_core_returns_none_when_nothing_found(self, project_dir):+ """resolve_core returns None when no file found in tiers 1/3/4."""+ resolver = PresetResolver(project_dir)+ result = resolver.resolve_core("nonexistent", "command")+ assert result is None++ def test_resolve_extension_command_via_manifest_skips_oserror_manifests(self, project_dir):+ """resolve_extension_command_via_manifest skips extensions whose manifest raises OSError."""+ import unittest.mock as mock++ ext_dir = project_dir / ".specify" / "extensions" / "bad-ext"+ cmd_dir = ext_dir / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "mycmd.md").write_text("---\ndescription: d\n---\n\nbody\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: bad-ext\n name: Bad\n version: 1.0.0\n"+ " description: d\n author: a\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n commands:\n"+ " - name: speckit.bad-ext.mycmd\n"+ " file: commands/mycmd.md\n"+ " description: My command\n"+ )++ resolver = PresetResolver(project_dir)+ # Simulate a permission error when opening the manifest file.+ with mock.patch("builtins.open", side_effect=PermissionError("denied")):+ result = resolver.resolve_extension_command_via_manifest("speckit.bad-ext.mycmd")++ assert result is None, "OSError during manifest load must be silently skipped"+++class TestExtensionPriorityResolution:+ """Test extension priority resolution with registered and unregistered extensions."""++ def test_unregistered_beats_registered_with_lower_precedence(self, project_dir):+ """Unregistered extension (implicit priority 10) beats registered with priority 20."""+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True, exist_ok=True)++ # Create registered extension with priority 20 (lower precedence than 10)+ registered_dir = extensions_dir / "registered-ext"+ (registered_dir / "templates").mkdir(parents=True)+ (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")++ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 20})++ # Create unregistered extension directory (implicit priority 10)+ unregistered_dir = extensions_dir / "unregistered-ext"+ (unregistered_dir / "templates").mkdir(parents=True)+ (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")++ # Unregistered (priority 10) should beat registered (priority 20)+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("test-template")+ assert result is not None+ assert "From Unregistered" in result.read_text()++ def test_registered_with_higher_precedence_beats_unregistered(self, project_dir):+ """Registered extension with priority 5 beats unregistered (implicit priority 10)."""+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True, exist_ok=True)++ # Create registered extension with priority 5 (higher precedence than 10)+ registered_dir = extensions_dir / "registered-ext"+ (registered_dir / "templates").mkdir(parents=True)+ (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")++ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 5})++ # Create unregistered extension directory (implicit priority 10)+ unregistered_dir = extensions_dir / "unregistered-ext"+ (unregistered_dir / "templates").mkdir(parents=True)+ (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")++ # Registered (priority 5) should beat unregistered (priority 10)+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("test-template")+ assert result is not None+ assert "From Registered" in result.read_text()++ def test_unregistered_attribution_with_priority_ordering(self, project_dir):+ """Test resolve_with_source correctly attributes unregistered extension."""+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True, exist_ok=True)++ # Create registered extension with priority 20+ registered_dir = extensions_dir / "registered-ext"+ (registered_dir / "templates").mkdir(parents=True)+ (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")++ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 20})++ # Create unregistered extension (implicit priority 10)+ unregistered_dir = extensions_dir / "unregistered-ext"+ (unregistered_dir / "templates").mkdir(parents=True)+ (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")++ # Attribution should show unregistered extension+ resolver = PresetResolver(project_dir)+ result = resolver.resolve_with_source("test-template")+ assert result is not None+ assert "unregistered-ext" in result["source"]+ assert "(unregistered)" in result["source"]++ def test_same_priority_sorted_alphabetically(self, project_dir):+ """Extensions with same priority are sorted alphabetically by ID."""+ extensions_dir = project_dir / ".specify" / "extensions"+ extensions_dir.mkdir(parents=True, exist_ok=True)++ # Create two unregistered extensions (both implicit priority 10)+ # "aaa-ext" should come before "zzz-ext" alphabetically+ zzz_dir = extensions_dir / "zzz-ext"+ (zzz_dir / "templates").mkdir(parents=True)+ (zzz_dir / "templates" / "test-template.md").write_text("# From ZZZ\n")++ aaa_dir = extensions_dir / "aaa-ext"+ (aaa_dir / "templates").mkdir(parents=True)+ (aaa_dir / "templates" / "test-template.md").write_text("# From AAA\n")++ # AAA should win due to alphabetical ordering at same priority+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("test-template")+ assert result is not None+ assert "From AAA" in result.read_text()+++class TestSelfTestPreset:+ """Template resolution using the bundled self-test preset."""++ def test_self_test_overrides_all_core_templates(self, project_dir):+ """Test that installing self-test overrides every core template."""+ # Set up core templates in the project+ templates_dir = project_dir / ".specify" / "templates"+ for name in CORE_TEMPLATE_NAMES:+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")++ # Install self-test preset+ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ # Every core template should now resolve from the preset+ resolver = PresetResolver(project_dir)+ for name in CORE_TEMPLATE_NAMES:+ result = resolver.resolve(name)+ assert result is not None, f"{name} did not resolve"+ content = result.read_text()+ assert "preset:self-test" in content, (+ f"{name} resolved but not from self-test preset"+ )++ def test_self_test_resolve_with_source(self, project_dir):+ """Test that resolve_with_source attributes templates to self-test."""+ templates_dir = project_dir / ".specify" / "templates"+ for name in CORE_TEMPLATE_NAMES:+ (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ resolver = PresetResolver(project_dir)+ for name in CORE_TEMPLATE_NAMES:+ result = resolver.resolve_with_source(name)+ assert result is not None, f"{name} did not resolve"+ assert "self-test" in result["source"], (+ f"{name} source is '{result['source']}', expected self-test"+ )++ def test_self_test_override_resolves_constitution_template(self, project_dir):+ """The preset override of constitution-template resolves to the preset file."""+ templates_dir = project_dir / ".specify" / "templates"+ (templates_dir / "constitution-template.md").write_text("# Core constitution\n")++ manager = PresetManager(project_dir)+ install_self_test_preset(manager)++ resolver = PresetResolver(project_dir)+ result = resolver.resolve("constitution-template", "template")+ assert result is not None+ assert "preset:self-test" in result.read_text()+++class TestPresetEnableDisable:+ """Disabled presets are excluded from template resolution."""++++++++++ def test_disabled_preset_excluded_from_resolution(self, project_dir, pack_dir):+ """Test that disabled presets are excluded from template resolution."""+ # Install preset with a template+ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ # Create a template in the preset directory+ preset_template = project_dir / ".specify" / "presets" / "test-pack" / "templates" / "test-template.md"+ preset_template.parent.mkdir(parents=True, exist_ok=True)+ preset_template.write_text("# Template from test-pack")++ resolver = PresetResolver(project_dir)++ # Template should be found when enabled+ result = resolver.resolve("test-template", "template")+ assert result is not None+ assert "test-pack" in str(result)++ # Disable the preset+ manager.registry.update("test-pack", {"enabled": False})++ # Template should NOT be found when disabled+ resolver2 = PresetResolver(project_dir)+ result2 = resolver2.resolve("test-template", "template")+ assert result2 is None+++class TestWrapStrategy:+ """Resolution of extension command, template, and script layers."""++ def test_extension_command_resolves_via_extension_directory(self, project_dir):+ """Extension commands (e.g. speckit.git.feature) resolve from the extension directory.++ Both _register_skills and register_commands pass the full cmd_name to+ _substitute_core_template, which tries the full name first via PresetResolver+ and finds speckit.git.feature.md in the extension commands directory.+ """+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ # Place the template where a real extension would install it+ ext_cmd_dir = project_dir / ".specify" / "extensions" / "git" / "commands"+ ext_cmd_dir.mkdir(parents=True, exist_ok=True)+ (ext_cmd_dir / "speckit.git.feature.md").write_text(+ "---\ndescription: git feature core\n---\n\n# Git Feature Core\n"+ )+ # Ensure a hyphenated or dot-separated fallback does NOT exist+ assert not (project_dir / ".specify" / "templates" / "commands" / "git.feature.md").exists()+ assert not (project_dir / ".specify" / "templates" / "commands" / "git-feature.md").exists()++ registrar = CommandRegistrar()+ body = "## Wrapper\n\n{CORE_TEMPLATE}\n"++ # Both call sites now pass the full cmd_name+ result, _ = _substitute_core_template(body, "speckit.git.feature", project_dir, registrar)++ assert "# Git Feature Core" in result+ assert "{CORE_TEMPLATE}" not in result++ def test_extension_command_resolves_via_manifest_when_filename_differs(self, project_dir):+ """Extension commands whose filename differs from the command name resolve via extension.yml.++ The selftest extension maps speckit.selftest.extension β commands/selftest.md.+ Name-based lookup would look for commands/speckit.selftest.extension.md and fail;+ manifest-based lookup must find the actual file declared in the manifest.+ """+ from specify_cli.presets import _substitute_core_template+ from specify_cli.agents import CommandRegistrar++ ext_dir = project_dir / ".specify" / "extensions" / "selftest"+ cmd_dir = ext_dir / "commands"+ cmd_dir.mkdir(parents=True, exist_ok=True)++ # File is named selftest.md, NOT speckit.selftest.extension.md+ (cmd_dir / "selftest.md").write_text(+ "---\ndescription: selftest core\n---\n\n# Selftest Core\n"+ )+ # Manifest maps the command name to the actual file+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: selftest\n name: Self-Test\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " commands:\n"+ " - name: speckit.selftest.extension\n"+ " file: commands/selftest.md\n"+ " description: Selftest command\n"+ )++ registrar = CommandRegistrar()+ body = "## Wrapper\n\n{CORE_TEMPLATE}\n"+ result, _ = _substitute_core_template(body, "speckit.selftest.extension", project_dir, registrar)++ assert "# Selftest Core" in result+ assert "{CORE_TEMPLATE}" not in result++ def test_extension_template_resolves_via_manifest_when_filename_differs(self, project_dir):+ """provides.templates entries resolve via extension.yml when the file+ doesn't sit at the conventional path.++ Regression coverage for #4010: manifest-declared templates/scripts+ must actually be consulted by the resolver, not just accepted by+ manifest validation.+ """+ ext_dir = project_dir / ".specify" / "extensions" / "reportext"+ tmpl_dir = ext_dir / "templates" / "nested"+ tmpl_dir.mkdir(parents=True, exist_ok=True)++ # File lives at a path convention-based lookup (templates/<name>.md)+ # would never find.+ (tmpl_dir / "actual.md").write_text("# Report Scaffold\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: reportext\n name: Report Ext\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " templates:\n"+ " - name: report-scaffold\n"+ " file: templates/nested/actual.md\n"+ " description: Report scaffold\n"+ )++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("report-scaffold", "template")+ assert layers, "expected the manifest-declared template to resolve"+ assert layers[0]["path"] == tmpl_dir / "actual.md"+ assert layers[0]["strategy"] == "replace"++ def test_extension_script_resolves_via_manifest_when_filename_differs(self, project_dir):+ """provides.scripts entries resolve via extension.yml when the file+ doesn't sit at the conventional path."""+ ext_dir = project_dir / ".specify" / "extensions" / "collectext"+ script_dir = ext_dir / "scripts" / "bash"+ script_dir.mkdir(parents=True, exist_ok=True)++ # File is under scripts/bash/, not directly under scripts/, so+ # convention-based lookup (scripts/<name>.sh) would never find it.+ (script_dir / "collect.sh").write_text("#!/usr/bin/env bash\necho collect\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: collectext\n name: Collect Ext\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " scripts:\n"+ " - name: myext-collect\n"+ " file: scripts/bash/collect.sh\n"+ " description: Data-collection helper\n"+ " runtimes: [bash]\n"+ )++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("myext-collect", "script")+ assert layers, "expected the manifest-declared script to resolve"+ assert layers[0]["path"] == script_dir / "collect.sh"+ assert layers[0]["strategy"] == "replace"++ def test_extension_template_convention_lookup_unaffected_when_undeclared(self, project_dir):+ """An extension template with no manifest entry still resolves via+ the pre-existing filename convention (no regression)."""+ ext_dir = project_dir / ".specify" / "extensions" / "conventionext"+ tmpl_dir = ext_dir / "templates"+ tmpl_dir.mkdir(parents=True, exist_ok=True)+ (tmpl_dir / "legacy-template.md").write_text("# Legacy Template\n")+ # No extension.yml at all -- purely convention-based, unregistered extension.++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("legacy-template", "template")+ assert layers, "expected convention-based lookup to still find the template"+ assert layers[0]["path"] == tmpl_dir / "legacy-template.md"++ def test_extension_manifest_wins_over_stale_conventional_file(self, project_dir):+ """A declared entry is authoritative even when a stale file also sits at+ the conventional path (templates/<name>.md) β the manifest must win,+ not the convention lookup, per #4010's acceptance criteria."""+ ext_dir = project_dir / ".specify" / "extensions" / "bothpathsext"+ (ext_dir / "templates").mkdir(parents=True, exist_ok=True)+ (ext_dir / "custom").mkdir(parents=True, exist_ok=True)++ # Stale file at the conventional path -- must NOT win.+ (ext_dir / "templates" / "report-scaffold.md").write_text("# Stale\n")+ # Declared file at a non-conventional path -- must win.+ (ext_dir / "custom" / "bar.md").write_text("# Actual\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: bothpathsext\n name: Both Paths Ext\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " templates:\n"+ " - name: report-scaffold\n"+ " file: custom/bar.md\n"+ " description: Report scaffold\n"+ )++ resolver = PresetResolver(project_dir)++ layers = resolver.collect_all_layers("report-scaffold", "template")+ assert layers, "expected the manifest-declared template to resolve"+ assert layers[0]["path"] == ext_dir / "custom" / "bar.md"++ resolved = resolver.resolve("report-scaffold", "template")+ assert resolved == ext_dir / "custom" / "bar.md"++ with_source = resolver.resolve_with_source("report-scaffold", "template")+ assert with_source["path"] == str(ext_dir / "custom" / "bar.md")++ def test_extension_manifest_declared_but_missing_file_does_not_fall_back(self, project_dir):+ """A declared entry whose file is missing is authoritative -- the+ resolver must not silently mask the typo by falling back to a+ conventional file that happens to also exist."""+ ext_dir = project_dir / ".specify" / "extensions" / "missingfileext"+ (ext_dir / "scripts").mkdir(parents=True, exist_ok=True)++ # A conventional file exists, but the manifest declares a different,+ # non-existent file for the same name.+ (ext_dir / "scripts" / "myext-collect.sh").write_text("#!/usr/bin/env bash\necho legacy\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: missingfileext\n name: Missing File Ext\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " scripts:\n"+ " - name: myext-collect\n"+ " file: scripts/does-not-exist.sh\n"+ " description: Data-collection helper\n"+ )++ resolver = PresetResolver(project_dir)++ assert resolver.collect_all_layers("myext-collect", "script") == []+ assert resolver.resolve("myext-collect", "script") is None++ def test_extension_script_resolve_and_resolve_with_source_parity(self, project_dir):+ """resolve() and resolve_with_source() must find a manifest-declared+ script at a non-conventional path, matching collect_all_layers()."""+ ext_dir = project_dir / ".specify" / "extensions" / "collectext2"+ script_dir = ext_dir / "scripts" / "bash"+ script_dir.mkdir(parents=True, exist_ok=True)++ (script_dir / "collect.sh").write_text("#!/usr/bin/env bash\necho collect\n")+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n id: collectext2\n name: Collect Ext 2\n version: 1.0.0\n"+ " description: test\n author: test\n repository: https://example.com\n"+ " license: MIT\n"+ "requires:\n speckit_version: '>=0.2.0'\n"+ "provides:\n"+ " scripts:\n"+ " - name: myext-collect2\n"+ " file: scripts/bash/collect.sh\n"+ " description: Data-collection helper\n"+ " runtimes: [bash]\n"+ )++ resolver = PresetResolver(project_dir)++ resolved = resolver.resolve("myext-collect2", "script")+ assert resolved == script_dir / "collect.sh"++ with_source = resolver.resolve_with_source("myext-collect2", "script")+ assert with_source is not None+ assert with_source["path"] == str(script_dir / "collect.sh")+ assert with_source["source"] == "extension:collectext2 (unregistered)"+++class TestResolveContent:+ """Test PresetResolver.resolve_content() composition."""++ def test_resolve_content_core_template(self, project_dir):+ """Test resolve_content returns core template when no composition."""+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Core Spec Template" in content++ def test_resolve_content_nonexistent(self, project_dir):+ """Test resolve_content returns None for nonexistent template."""+ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("nonexistent")+ assert content is None++ def test_resolve_content_unreadable_winning_layer_returns_none(self, project_dir):+ """An undecodable winning layer must yield None, not a raw traceback.++ ``collect_all_layers`` deliberately keeps a non-UTF-8 legacy command+ layer (with its ``replace`` default) so unrelated commands still+ resolve. ``resolve_content`` then read that same file without a+ boundary, so the tolerated layer crashed with ``UnicodeDecodeError``+ at composition time β reachable from ``specify preset add`` via+ ``_register_commands``. The documented contract is "Composed content+ string, or None if not found".+ """+ presets_dir = project_dir / ".specify" / "presets"+ command_path = (+ presets_dir / "legacy-pack" / "commands" / "speckit.legacy.md"+ )+ command_path.parent.mkdir(parents=True)+ command_path.write_bytes(b"\xff\xfe")+ PresetRegistry(presets_dir).add(+ "legacy-pack", {"version": "1.0.0", "priority": 10}+ )++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.legacy", "command")+ assert content is None++ def test_resolve_content_unreadable_base_under_composing_layer(+ self, project_dir, temp_dir, valid_pack_data+ ):+ """An undecodable base beneath a valid composing layer yields None.++ Covers the base-read guard: the winning layer composes (append), so+ resolution reads the base layer beneath it β here the core template,+ corrupted to non-UTF-8 β and must return None instead of crashing.+ """+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ core_spec = project_dir / ".specify" / "templates" / "spec-template.md"+ core_spec.write_bytes(b"\xff\xfe")++ resolver = PresetResolver(project_dir)+ assert resolver.resolve_content("spec-template") is None++ def test_resolve_content_unreadable_composing_layer(+ self, project_dir, temp_dir, valid_pack_data, monkeypatch+ ):+ """An unreadable composing layer over a valid base yields None.++ Covers the composition-loop read and the ``OSError`` half of the+ boundary: the base (core template) reads fine, but the append layer+ raises a mocked ``PermissionError`` β mocked so the case also holds+ under privileged CI where permission bits are not enforced.+ """+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ layer_path = (+ project_dir / ".specify" / "presets" / "append-pack"+ / "templates" / "spec-template.md"+ )+ assert layer_path.is_file()+ original_read_text = Path.read_text++ def failing_read_text(self_path, *args, **kwargs):+ if self_path == layer_path:+ raise PermissionError(13, "Permission denied")+ return original_read_text(self_path, *args, **kwargs)++ monkeypatch.setattr(Path, "read_text", failing_read_text)++ resolver = PresetResolver(project_dir)+ assert resolver.resolve_content("spec-template") is None++ def test_resolve_content_replace_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with default replace strategy."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(+ _create_pack(temp_dir, valid_pack_data, "replace-pack",+ "# Replaced Content\n"),+ "0.1.5"+ )++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Replaced Content" in content+ assert "Core Spec Template" not in content++ def test_resolve_content_append_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with append strategy."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Core Spec Template" in content+ assert "Appended Section" in content+ # Core should come first, appended after+ assert content.index("Core Spec Template") < content.index("Appended Section")++ def test_resolve_content_prepend_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with prepend strategy."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "prepend-pack", "name": "Prepend"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "prepend",+ }]+ }+ pack_dir = temp_dir / "prepend-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Security Header\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Security Header" in content+ assert "Core Spec Template" in content+ # Prepended content should come first+ assert content.index("Security Header") < content.index("Core Spec Template")++ def test_resolve_content_wrap_strategy(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with wrap strategy for templates."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-pack", "name": "Wrap"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "wrap",+ }]+ }+ pack_dir = temp_dir / "wrap-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text(+ "# Wrapper Start\n\n{CORE_TEMPLATE}\n\n# Wrapper End\n"+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Wrapper Start" in content+ assert "Core Spec Template" in content+ assert "Wrapper End" in content+ # Wrapper should surround core+ assert content.index("Wrapper Start") < content.index("Core Spec Template")+ assert content.index("Core Spec Template") < content.index("Wrapper End")++ def test_resolve_content_wrap_strategy_script(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with wrap strategy for scripts uses $CORE_SCRIPT."""+ # Create core script+ scripts_dir = project_dir / ".specify" / "templates" / "scripts"+ scripts_dir.mkdir(parents=True, exist_ok=True)+ (scripts_dir / "test-script.sh").write_text("echo 'core script'\n")++ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "script-wrap", "name": "Script Wrap"}+ pack_data["provides"] = {+ "templates": [{+ "type": "script",+ "name": "test-script",+ "file": "scripts/test-script.sh",+ "strategy": "wrap",+ }]+ }+ pack_dir = temp_dir / "script-wrap"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "scripts").mkdir()+ (pack_dir / "scripts" / "test-script.sh").write_text(+ "#!/bin/bash\necho 'before'\n$CORE_SCRIPT\necho 'after'\n"+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("test-script", "script")+ assert content is not None+ assert "echo 'before'" in content+ assert "echo 'core script'" in content+ assert "echo 'after'" in content++ def test_resolve_content_multi_preset_chain(self, project_dir, temp_dir, valid_pack_data):+ """Test multi-preset composition chain: prepend + append stacking."""+ # Create preset A (priority 1): prepend security header+ pack_a_data = {**valid_pack_data}+ pack_a_data["preset"] = {**valid_pack_data["preset"], "id": "preset-a", "name": "A"}+ pack_a_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "prepend",+ }]+ }+ pack_a_dir = temp_dir / "preset-a"+ pack_a_dir.mkdir()+ with open(pack_a_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_a_data, f)+ (pack_a_dir / "templates").mkdir()+ (pack_a_dir / "templates" / "spec-template.md").write_text("## Security Header\n")++ # Create preset B (priority 2): append compliance footer+ pack_b_data = {**valid_pack_data}+ pack_b_data["preset"] = {**valid_pack_data["preset"], "id": "preset-b", "name": "B"}+ pack_b_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_b_dir = temp_dir / "preset-b"+ pack_b_dir.mkdir()+ with open(pack_b_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_b_data, f)+ (pack_b_dir / "templates").mkdir()+ (pack_b_dir / "templates" / "spec-template.md").write_text("## Compliance Footer\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_a_dir, "0.1.5", priority=1)+ manager.install_from_directory(pack_b_dir, "0.1.5", priority=2)++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ # Result: <security header> + <core> + <compliance footer>+ assert "Security Header" in content+ assert "Core Spec Template" in content+ assert "Compliance Footer" in content+ assert content.index("Security Header") < content.index("Core Spec Template")+ assert content.index("Core Spec Template") < content.index("Compliance Footer")++ def test_resolve_content_override_trumps_composition(self, project_dir, temp_dir, valid_pack_data):+ """Test that project overrides trump composition (replace at top priority)."""+ # Install a composing preset+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "append-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Appended\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ # Create project override (replaces everything)+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "spec-template.md").write_text("# Override Only\n")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content is not None+ assert "Override Only" in content+ # Override replaces, so appended content should not be visible+ assert "Core Spec Template" not in content++ def test_resolve_content_command_type(self, project_dir, temp_dir, valid_pack_data):+ """Test resolve_content with command template type."""+ # Create core command using stem naming (matches real layout: plan.md, not speckit.plan.md)+ commands_dir = project_dir / ".specify" / "templates" / "commands"+ commands_dir.mkdir(parents=True, exist_ok=True)+ (commands_dir / "plan.md").write_text("# Core Plan Command\n")++ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "cmd-append", "name": "CmdAppend"}+ pack_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.plan",+ "file": "commands/speckit.plan.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "cmd-append"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "commands").mkdir()+ (pack_dir / "commands" / "speckit.plan.md").write_text("## Additional Instructions\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.plan", "command")+ assert content is not None+ assert "Core Plan Command" in content+ assert "Additional Instructions" in content++ def test_resolve_content_command_frontmatter_stripping(self, project_dir, temp_dir, valid_pack_data):+ """Test that command composition strips frontmatter from lower layers+ and reattaches only the highest-priority frontmatter."""+ # Create core command with frontmatter+ commands_dir = project_dir / ".specify" / "templates" / "commands"+ commands_dir.mkdir(parents=True, exist_ok=True)+ (commands_dir / "check.md").write_text(+ "---\ndescription: Core check command\n---\nCore body content\n"+ )++ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "fm-test", "name": "FmTest"}+ pack_data["provides"] = {+ "templates": [{+ "type": "command",+ "name": "speckit.check",+ "file": "commands/speckit.check.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "fm-test"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "commands").mkdir()+ (pack_dir / "commands" / "speckit.check.md").write_text(+ "---\ndescription: Preset check override\n---\nPreset body content\n"+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.check", "command")+ assert content is not None+ # Should have the preset (highest-priority) frontmatter+ assert "Preset check override" in content+ # Should have both bodies+ assert "Core body content" in content+ assert "Preset body content" in content+ # Core frontmatter should NOT appear in the body+ assert content.count("---") == 2 # only one frontmatter block (opening + closing)++ def test_resolve_content_blank_line_separator(self, project_dir, temp_dir, valid_pack_data):+ """Test that prepend/append use blank line separator."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "sep-test", "name": "SepTest"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "sep-test"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("appended")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ # Should have blank line separator+ assert "\n\n" in content++ def test_resolve_content_replace_over_wrap(self, project_dir, temp_dir, valid_pack_data):+ """Top-priority replace layer should win even if a lower layer uses wrap."""+ # Install a low-priority wrap preset (with no placeholder β would fail if evaluated)+ wrap_data = {**valid_pack_data}+ wrap_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-lo", "name": "WrapLo"}+ wrap_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "wrap",+ }]+ }+ wrap_dir = temp_dir / "wrap-lo"+ wrap_dir.mkdir()+ with open(wrap_dir / "preset.yml", "w") as f:+ yaml.dump(wrap_data, f)+ (wrap_dir / "templates").mkdir()+ # Intentionally missing {CORE_TEMPLATE} β would error if composition ran+ (wrap_dir / "templates" / "spec-template.md").write_text("wrapper without placeholder")++ manager = PresetManager(project_dir)+ manager.install_from_directory(wrap_dir, "0.1.5", priority=10)++ # Install a high-priority replace preset+ rep_data = {**valid_pack_data}+ rep_data["preset"] = {**valid_pack_data["preset"], "id": "rep-hi", "name": "RepHi"}+ rep_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ }]+ }+ rep_dir = temp_dir / "rep-hi"+ rep_dir.mkdir()+ with open(rep_dir / "preset.yml", "w") as f:+ yaml.dump(rep_data, f)+ (rep_dir / "templates").mkdir()+ (rep_dir / "templates" / "spec-template.md").write_text("# Replaced content\n")++ manager.install_from_directory(rep_dir, "0.1.5", priority=1)++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("spec-template")+ assert content == "# Replaced content\n"++ @pytest.mark.parametrize("strategy", ["append", "prepend", "wrap"])+ def test_resolve_content_rewrites_extension_base_subdir_paths(+ self, project_dir, temp_dir, strategy+ ):+ """Composing over an extension-provided base command must resolve the+ extension's own subdir references (agents/, knowledge-base/) to their+ installed location (#2101), not just when the extension wins outright.+ """+ extension_dir = project_dir / ".specify" / "extensions" / "fakeext"+ (extension_dir / "commands").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)+ (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")+ (extension_dir / "commands" / "cmd.md").write_text(+ "---\ndescription: Extension fakeext cmd\n---\n\n"+ "Read agents/control/commander.md for context.\n"+ )+ extension_manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "fakeext",+ "name": "Fake Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.fakeext.cmd",+ "file": "commands/cmd.md",+ "description": "Fake extension command",+ }+ ]+ },+ }+ with open(extension_dir / "extension.yml", "w") as f:+ yaml.dump(extension_manifest, f)++ preset_dir = temp_dir / f"ext-base-{strategy}"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ overlay_body = (+ "{CORE_TEMPLATE}\n## Extra\n" if strategy == "wrap" else "## Extra\n"+ )+ (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(+ f"---\ndescription: Preset overlay\n---\n\n{overlay_body}"+ )+ preset_manifest = {+ "schema_version": "1.0",+ "preset": {+ "id": f"ext-base-{strategy}",+ "name": "Ext Base",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.fakeext.cmd",+ "file": "commands/speckit.fakeext.cmd.md",+ "strategy": strategy,+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(preset_manifest, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ content = resolver.resolve_content("speckit.fakeext.cmd", "command")+ assert content is not None+ assert ".specify/extensions/fakeext/agents/control/commander.md" in content+ assert "Read agents/control" not in content+ assert "## Extra" in content+++class TestCollectAllLayers:+ """Test PresetResolver.collect_all_layers() method."""++ def test_non_utf8_legacy_command_keeps_replace_strategy(self, project_dir):+ presets_dir = project_dir / ".specify" / "presets"+ command_path = (+ presets_dir / "legacy-pack" / "commands" / "speckit.legacy.md"+ )+ command_path.parent.mkdir(parents=True)+ command_path.write_bytes(b"\xff\xfe")+ PresetRegistry(presets_dir).add(+ "legacy-pack", {"version": "1.0.0", "priority": 10}+ )++ layers = PresetResolver(project_dir).collect_all_layers(+ "speckit.legacy", "command"+ )++ assert layers[0]["path"] == command_path+ assert layers[0]["strategy"] == "replace"++ def test_single_core_layer(self, project_dir):+ """Test collecting layers with only core template."""+ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 1+ assert layers[0]["source"] == "core"+ assert layers[0]["strategy"] == "replace"++ def test_layers_include_presets(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers include installed preset."""+ manager = PresetManager(project_dir)+ pack_dir = _create_pack(temp_dir, valid_pack_data, "test-pack",+ "# From Pack\n")+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 2+ # Highest priority first+ assert "test-pack" in layers[0]["source"]+ assert layers[1]["source"] == "core"++ def test_layers_order_matches_priority(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers are ordered by priority (highest first)."""+ manager = PresetManager(project_dir)+ for pid, prio in [("pack-lo", 10), ("pack-hi", 1)]:+ d = {**valid_pack_data}+ d["preset"] = {**valid_pack_data["preset"], "id": pid, "name": pid}+ p = temp_dir / pid+ p.mkdir()+ with open(p / "preset.yml", 'w') as f:+ yaml.dump(d, f)+ (p / "templates").mkdir()+ (p / "templates" / "spec-template.md").write_text(f"# {pid}\n")+ manager.install_from_directory(p, "0.1.5", priority=prio)++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ assert len(layers) == 3 # pack-hi, pack-lo, core+ assert "pack-hi" in layers[0]["source"]+ assert "pack-lo" in layers[1]["source"]+ assert layers[2]["source"] == "core"++ def test_layers_read_strategy_from_manifest(self, project_dir, temp_dir, valid_pack_data):+ """Test that layers read strategy from preset manifest."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": "strat-pack", "name": "Strat"}+ pack_data["provides"] = {+ "templates": [{+ "type": "template",+ "name": "spec-template",+ "file": "templates/spec-template.md",+ "strategy": "append",+ }]+ }+ pack_dir = temp_dir / "strat-pack"+ pack_dir.mkdir()+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)+ (pack_dir / "templates").mkdir()+ (pack_dir / "templates" / "spec-template.md").write_text("## Footer\n")++ manager = PresetManager(project_dir)+ manager.install_from_directory(pack_dir, "0.1.5")++ resolver = PresetResolver(project_dir)+ layers = resolver.collect_all_layers("spec-template")+ # Preset layer should have strategy=append+ assert layers[0]["strategy"] == "append"+ # Core layer should be replace+ assert layers[1]["strategy"] == "replace"+++def _create_pack(temp_dir, valid_pack_data, pack_id, content,+ strategy="replace", template_type="template",+ template_name="spec-template"):+ """Helper to create a preset pack directory."""+ pack_data = {**valid_pack_data}+ pack_data["preset"] = {**valid_pack_data["preset"], "id": pack_id, "name": pack_id}++ tmpl_entry = {+ "type": template_type,+ "name": template_name,+ }+ if template_type == "script":+ tmpl_entry["file"] = f"scripts/{template_name}.sh"+ elif template_type == "command":+ tmpl_entry["file"] = f"commands/{template_name}.md"+ else:+ tmpl_entry["file"] = f"templates/{template_name}.md"+ if strategy != "replace":+ tmpl_entry["strategy"] = strategy+ pack_data["provides"] = {"templates": [tmpl_entry]}++ pack_dir = temp_dir / pack_id+ pack_dir.mkdir(exist_ok=True)+ with open(pack_dir / "preset.yml", 'w') as f:+ yaml.dump(pack_data, f)++ if template_type == "script":+ subdir = pack_dir / "scripts"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.sh").write_text(content)+ elif template_type == "command":+ subdir = pack_dir / "commands"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.md").write_text(content)+ else:+ subdir = pack_dir / "templates"+ subdir.mkdir(exist_ok=True)+ (subdir / f"{template_name}.md").write_text(content)++ return pack_dirdiff --git a/tests/test_extension_skills.py b/tests/test_extension_skills.pyindex 3622fd994..3f65585a3 100644--- a/tests/test_extension_skills.py+++ b/tests/test_extension_skills.py@@ -1717,7 +1717,7 @@ class TestExtensionSkillRegistration:Mirrors the analogous preset-side fix(``test_toggle_command_to_skills_preserves_old_command_on_skills_failure``- in ``tests/test_presets.py``): before the fix, the stale+ in ``tests/specify_cli/presets/test_manager_commands.py``): before the fix, the stalecommand-mode file/tracking was unregistered unconditionally as soonas the commands phase was skipped for ``skills_mode_active``,regardless of whether the subsequent, independently-falliblediff --git a/tests/test_presets.py b/tests/test_presets.pyindex a7e590b07..11f19f6b9 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -1,48 +1,27 @@-"""-Unit tests for the preset system.--Tests cover:-- Preset manifest validation-- Preset registry operations-- Preset manager installation/removal-- Template catalog search-- Template resolver priority stack-- Extension-provided templates+"""Cross-domain preset workflows and bundled-content contracts.++Domain unit tests mirror src/specify_cli/presets/_*.py under+tests/specify_cli/presets/test_*.py; command tests live alongside them."""-import pytest-import ioimport json-import tarfile-import shutilimport zipfile-from contextlib import contextmanagerfrom pathlib import Path-from datetime import datetime, timezone-from unittest.mock import MagicMock+import pytestimport yaml+from specify_cli.extensions import ExtensionRegistryfrom specify_cli.presets import (- PresetManifest,- PresetRegistry,PresetManager,- PresetCatalog,- PresetCatalogEntry,+ PresetManifest,PresetResolver,- PresetError,- PresetValidationError,- PresetCompatibilityError,- VALID_PRESET_TEMPLATE_TYPES,)-from specify_cli.extensions import ExtensionRegistryfrom tests.specify_cli.presets import _fixturesfrom tests.specify_cli.presets._helpers import (CORE_TEMPLATE_NAMES,SELF_TEST_PRESET_DIR,- install_constitution_sync_preset,install_self_test_preset,- make_convention_constitution_preset as _make_convention_constitution_preset,)temp_dir = _fixtures.temp_dir@@ -51,819 +30,70 @@ pack_dir = _fixtures.pack_dirproject_dir = _fixtures.project_dir-# ===== PresetManifest Tests =====---class TestPresetManifest:- """Test PresetManifest validation and parsing."""+class TestIntegration:+ """Integration tests for complete preset workflows."""- def test_valid_manifest(self, pack_dir):- """Test loading a valid manifest."""- manifest = PresetManifest(pack_dir / "preset.yml")+ def test_full_install_resolve_remove_cycle(self, project_dir, pack_dir):+ """Test complete lifecycle: install β resolve β remove."""+ # Install+ manager = PresetManager(project_dir)+ manifest = manager.install_from_directory(pack_dir, "0.1.5")assert manifest.id == "test-pack"- assert manifest.name == "Test Preset"- assert manifest.version == "1.0.0"- assert manifest.description == "A test preset"- assert manifest.author == "Test Author"- assert manifest.requires_speckit_version == ">=0.1.0"- assert len(manifest.templates) == 1- assert manifest.tags == ["testing", "example"]-- def test_missing_manifest(self, temp_dir):- """Test that missing manifest raises error."""- with pytest.raises(PresetValidationError, match="Manifest not found"):- PresetManifest(temp_dir / "nonexistent.yml")-- def test_invalid_yaml(self, temp_dir):- """Test that invalid YAML raises error."""- bad_file = temp_dir / "bad.yml"- bad_file.write_text(": invalid: yaml: {{{")- with pytest.raises(PresetValidationError, match="Invalid YAML"):- PresetManifest(bad_file)-- def test_utf8_non_ascii_description_loads(self, temp_dir, valid_pack_data):- """Regression for #2325: non-ASCII (UTF-8) description loads on any platform.-- On Windows, Python's default text-mode encoding is the locale codepage- (e.g. cp1252/GBK), which raises UnicodeDecodeError on UTF-8 bytes- outside the ASCII range. The loader must open with encoding='utf-8'.- """- valid_pack_data["preset"]["description"] = "δΈζζ΅θ― β Γ©mojis π"- manifest_path = temp_dir / "preset.yml"- manifest_path.write_bytes(- yaml.safe_dump(valid_pack_data, allow_unicode=True).encode("utf-8")- )-- manifest = PresetManifest(manifest_path)- assert manifest.description == "δΈζζ΅θ― β Γ©mojis π"-- def test_invalid_utf8_bytes_raises_validation_error(self, temp_dir):- """Negative case: file containing invalid UTF-8 bytes raises PresetValidationError, not raw UnicodeDecodeError."""- manifest_path = temp_dir / "preset.yml"- manifest_path.write_bytes(b"\xff\xfe not valid utf-8 \xff\n")-- with pytest.raises(PresetValidationError, match="not valid UTF-8"):- PresetManifest(manifest_path)-- def test_non_mapping_yaml_raises_validation_error(self, temp_dir):- """Manifest whose YAML root is a scalar or list raises PresetValidationError, not TypeError."""- manifest_path = temp_dir / "preset.yml"- for bad_content in ("42\n", "[1, 2]\n"):- manifest_path.write_text(bad_content, encoding="utf-8")- with pytest.raises(PresetValidationError, match="YAML mapping"):- PresetManifest(manifest_path)-- @pytest.mark.parametrize("section", ["preset", "requires", "provides"])- @pytest.mark.parametrize("bad_value", [None, [], "text"])- def test_required_section_not_mapping_raises_validation_error(- self, temp_dir, valid_pack_data, section, bad_value- ):- """Required manifest sections reject null, list, and scalar values."""- valid_pack_data[section] = bad_value- manifest_path = temp_dir / "preset.yml"- manifest_path.write_text(- yaml.safe_dump(valid_pack_data),- encoding="utf-8",- )-- with pytest.raises(- PresetValidationError,- match=rf"Invalid {section}: expected a mapping",- ):- PresetManifest(manifest_path)-- @pytest.mark.parametrize("field", ["id", "name", "version", "description"])- @pytest.mark.parametrize("bad", [1.0, 5, None, ["a"], {"a": 1}, True])- def test_preset_metadata_field_not_string_raises_validation_error(- self, temp_dir, valid_pack_data, field, bad- ):- """A non-string preset.<field> raises PresetValidationError, not a raw- TypeError.-- The loop over these four fields only checked key PRESENCE, then fed the- values to ``re.match`` (id) and ``packaging.Version`` (version), both of- which raise a bare TypeError on a non-string. YAML makes that an easy- authoring slip: unquoted ``version: 1.0`` parses as a float and ``id: 2``- as an int. TypeError is not a PresetValidationError, so it escaped- list_installed()'s "Corrupted preset" fallback and made- `specify preset list` exit 1 with a raw traceback, hiding every healthy- preset too. The sibling IntegrationDescriptor already type-checks the- same four fields.- """- valid_pack_data["preset"][field] = bad- manifest_path = temp_dir / "preset.yml"- manifest_path.write_text(yaml.safe_dump(valid_pack_data), encoding="utf-8")-- with pytest.raises(- PresetValidationError,- match=rf"Invalid preset\.{field}: expected a string",- ):- PresetManifest(manifest_path)-- @pytest.mark.parametrize("field", ["name", "file"])- @pytest.mark.parametrize("bad", [1.0, 5, None, ["a"], {"a": 1}, True])- def test_template_entry_field_not_string_raises_validation_error(- self, temp_dir, valid_pack_data, field, bad- ):- """A non-string template ``name``/``file`` raises PresetValidationError.-- ``name`` reaches ``re.match`` and ``file`` reaches ``os.path.normpath``;- both raise a bare TypeError on a non-string. The sibling extension- manifest already rejects a non-string command ``file`` via- relative_extension_path_violation().- """- valid_pack_data["provides"]["templates"][0][field] = bad- manifest_path = temp_dir / "preset.yml"- manifest_path.write_text(yaml.safe_dump(valid_pack_data), encoding="utf-8")-- with pytest.raises(- PresetValidationError,- match=rf"Invalid template {field}: expected a string",- ):- PresetManifest(manifest_path)-- def test_one_bad_manifest_does_not_hide_healthy_presets(self, temp_dir):- """End-to-end guard for the symptom: an unquoted ``version: 1.0`` in one- installed preset must degrade to "Corrupted preset" and still let- list_installed() report the healthy ones, instead of raising TypeError- out of the whole call.- """- preset_root = temp_dir / ".specify" / "presets"- for pack_id, version in (("good-pack", '"1.0.0"'), ("bad-pack", "1.0")):- pack_path = preset_root / pack_id- pack_path.mkdir(parents=True, exist_ok=True)- (pack_path / "preset.yml").write_text(- f"""schema_version: "1.0"-preset:- id: {pack_id}- name: {pack_id}- version: {version}- description: desc-requires:- speckit_version: ">=0.1.0"-provides:- templates:- - type: template- name: spec- file: templates/spec.md-""",- encoding="utf-8",- )- (preset_root / ".registry").write_text(- json.dumps(- {- "schema_version": "1.0",- "presets": {- "good-pack": {"version": "1.0.0", "enabled": True},- "bad-pack": {"version": "1.0", "enabled": True},- },- }- ),- encoding="utf-8",- )- listed = {row["id"]: row for row in PresetManager(temp_dir).list_installed()}-- assert set(listed) == {"good-pack", "bad-pack"}- assert "Corrupted" not in listed["good-pack"]["description"]- assert "Corrupted" in listed["bad-pack"]["description"]-- @pytest.mark.parametrize(- "bad",- [- 5, "oops", {"a": 1}, # truthy non-lists- 0, False, None, "", {}, # FALSY non-lists: must not fall through to- # the misleading "at least one template"- ],- )- def test_non_list_templates_raises_validation_error(- self, temp_dir, valid_pack_data, bad- ):- """A non-list provides.templates raises the accurate type error, not a raw- 'int object is not iterable' TypeError and not the misleading "must provide- at least one template" (which a falsy non-list hit while the type check- sat behind the emptiness check) β mirrors ExtensionManifest."""- valid_pack_data["provides"]["templates"] = bad- manifest_path = temp_dir / "preset.yml"- manifest_path.write_text(yaml.dump(valid_pack_data), encoding="utf-8")- with pytest.raises(PresetValidationError, match="templates.*expected a list"):- PresetManifest(manifest_path)-- # NOTE: the empty-list case (a well-typed container with no templates, which- # must keep the "must provide at least one template" message after the- # type-before-emptiness reordering) is already covered by- # test_no_templates_provided below.-- @pytest.mark.parametrize("bad_entry", [None, 5, "oops", ["nested"]])- def test_non_mapping_template_entry_raises_validation_error(- self, temp_dir, valid_pack_data, bad_entry- ):- """A non-mapping template entry (null/scalar/list) raises PresetValidationError,- not a raw 'argument of type ... is not iterable' TypeError from the- `"type" not in tmpl` membership test β mirrors ExtensionManifest."""- valid_pack_data["provides"]["templates"] = [bad_entry]- manifest_path = temp_dir / "preset.yml"- manifest_path.write_text(yaml.dump(valid_pack_data), encoding="utf-8")- with pytest.raises(PresetValidationError, match="must be a mapping"):- PresetManifest(manifest_path)-- def test_missing_schema_version(self, temp_dir, valid_pack_data):- """Test missing schema_version field."""- del valid_pack_data["schema_version"]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Missing required field: schema_version"):- PresetManifest(manifest_path)-- def test_wrong_schema_version(self, temp_dir, valid_pack_data):- """Test unsupported schema version."""- valid_pack_data["schema_version"] = "2.0"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Unsupported schema version"):- PresetManifest(manifest_path)-- def test_missing_pack_id(self, temp_dir, valid_pack_data):- """Test missing preset.id field."""- del valid_pack_data["preset"]["id"]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Missing preset.id"):- PresetManifest(manifest_path)-- def test_invalid_pack_id_format(self, temp_dir, valid_pack_data):- """Test invalid pack ID format."""- valid_pack_data["preset"]["id"] = "Invalid_ID"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid preset ID"):- PresetManifest(manifest_path)-- def test_invalid_version(self, temp_dir, valid_pack_data):- """Test invalid semantic version."""- valid_pack_data["preset"]["version"] = "not-a-version"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid version"):- PresetManifest(manifest_path)-- def test_missing_speckit_version(self, temp_dir, valid_pack_data):- """Test missing requires.speckit_version."""- del valid_pack_data["requires"]["speckit_version"]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Missing requires.speckit_version"):- PresetManifest(manifest_path)-- @pytest.mark.parametrize(- "bad",- [- 1.0, # unquoted YAML float -- the likeliest authoring slip- 5, # unquoted int- True, # YAML `yes`/`true`- None, # `speckit_version:` written but left empty- [">=0.1.0"], # iterable: slips past SpecifierSet() entirely- {"min": "0.1"}, # iterable: same- " ", # blank string must not mean "any version"- ],- )- def test_non_string_speckit_version(self, temp_dir, valid_pack_data, bad):- """A non-string requires.speckit_version must be a PresetValidationError.-- It was presence-checked only, so it reached ``SpecifierSet(required)`` in- check_compatibility(), which is guarded by ``except InvalidSpecifier``- alone. A non-string escapes that guard two ways: scalars raise TypeError- from the constructor, and a list/dict is iterable so SpecifierSet accepts- it and the failure surfaces later as ``AttributeError: 'str' object has no- attribute 'filter'`` from inside .contains().- """- valid_pack_data["requires"]["speckit_version"] = bad- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(- PresetValidationError, match="Invalid requires.speckit_version"- ):- PresetManifest(manifest_path)-- def test_no_templates_provided(self, temp_dir, valid_pack_data):- """Test pack with no templates."""- valid_pack_data["provides"]["templates"] = []- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="must provide at least one template"):- PresetManifest(manifest_path)-- def test_invalid_template_type(self, temp_dir, valid_pack_data):- """Test template with invalid type."""- valid_pack_data["provides"]["templates"][0]["type"] = "invalid"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid template type"):- PresetManifest(manifest_path)-- def test_valid_template_types(self):- """Test that all expected template types are valid."""- assert "template" in VALID_PRESET_TEMPLATE_TYPES- assert "command" in VALID_PRESET_TEMPLATE_TYPES- assert "script" in VALID_PRESET_TEMPLATE_TYPES-- def test_template_missing_required_fields(self, temp_dir, valid_pack_data):- """Test template missing required fields."""- valid_pack_data["provides"]["templates"] = [{"type": "template"}]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="missing 'type', 'name', or 'file'"):- PresetManifest(manifest_path)-- def test_invalid_template_name_format(self, temp_dir, valid_pack_data):- """Test template with invalid name format."""- valid_pack_data["provides"]["templates"][0]["name"] = "Invalid Name"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid template name"):- PresetManifest(manifest_path)-- def test_get_hash(self, pack_dir):- """Test manifest hash calculation."""- manifest = PresetManifest(pack_dir / "preset.yml")- hash_val = manifest.get_hash()- assert hash_val.startswith("sha256:")- import hashlib- content = (pack_dir / "preset.yml").read_bytes()- expected = f"sha256:{hashlib.sha256(content).hexdigest()}"- assert hash_val == expected-- def test_multiple_templates(self, temp_dir, valid_pack_data):- """Test pack with multiple templates of different types."""- valid_pack_data["provides"]["templates"] = [- {"type": "template", "name": "spec-template", "file": "templates/spec-template.md"},- {"type": "template", "name": "plan-template", "file": "templates/plan-template.md"},- {"type": "command", "name": "specify", "file": "commands/specify.md"},- {"type": "script", "name": "create-new-feature", "file": "scripts/create-new-feature.sh"},- ]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- manifest = PresetManifest(manifest_path)- assert len(manifest.templates) == 4-- def test_duplicate_template_name_and_type_raises_validation_error(- self, temp_dir, valid_pack_data- ):- """A later entry with the same (name, type) pair must be rejected.-- ``PresetResolver._manifest_declared_template`` returns the FIRST- 'provides.templates' entry matching a given (name, type) pair, so a- later duplicate would be silently unreachable while still being- counted by ``PresetManifest.templates`` -- mirroring the sibling bug- fixed for ``ExtensionManifest``'s provides.templates/scripts (#4016).- """- valid_pack_data["provides"]["templates"] = [- {"type": "command", "name": "specify", "file": "commands/specify-v1.md"},- {"type": "command", "name": "specify", "file": "commands/specify-v2.md"},- ]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Duplicate template name"):- PresetManifest(manifest_path)-- def test_same_name_different_type_templates_allowed(- self, temp_dir, valid_pack_data- ):- """The same name may recur across different template types."""- valid_pack_data["provides"]["templates"] = [- {"type": "template", "name": "specify", "file": "templates/specify.md"},- {"type": "command", "name": "specify", "file": "commands/specify.md"},- ]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- manifest = PresetManifest(manifest_path)- assert len(manifest.templates) == 2-- def test_requires_extensions_absent_is_valid(self, temp_dir, valid_pack_data):- """A preset with no declared dependencies stays valid and reports none."""- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- assert PresetManifest(manifest_path).requires_extensions == []-- def test_requires_extensions_accepts_both_forms(self, temp_dir, valid_pack_data):- """Bare ids and mappings normalize to the same shape."""- valid_pack_data["requires"]["extensions"] = [- "speckit-inventory",- {"id": "other-ext", "version": ">=1.2.0", "required": False},- ]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)-- assert PresetManifest(manifest_path).requires_extensions == [- {"id": "speckit-inventory", "version": None, "required": True},- {"id": "other-ext", "version": ">=1.2.0", "required": False},- ]-- @pytest.mark.parametrize(- "bad, expected",- [- ("speckit-inventory", "Invalid requires.extensions"), # str, not list- ({"id": "x"}, "Invalid requires.extensions"), # mapping, not list- ([123], r"Invalid requires\.extensions\[0\]"), # member not str/mapping- ([None], r"Invalid requires\.extensions\[0\]"),- ([{"version": ">=1"}], r"Missing requires\.extensions\[0\]\.id"),- ([{"id": 5}], r"Invalid requires\.extensions\[0\]\.id"),- ([{"id": "Bad_ID"}], r"Invalid requires\.extensions\[0\]\.id"),- (["Bad_ID"], r"Invalid requires\.extensions\[0\]\.id"),- ([{"id": "x", "version": 1.0}], r"Invalid requires\.extensions\[0\]\.version"),- ([{"id": "x", "version": " "}], r"Invalid requires\.extensions\[0\]\.version"),- ([{"id": "x", "version": "nonsense"}], r"Invalid requires\.extensions\[0\]\.version"),- ([{"id": "x", "required": "yes"}], r"Invalid requires\.extensions\[0\]\.required"),- # `$` also matches before a trailing newline, so an anchored- # re.match would admit these while the resolver's fullmatch-based- # safe-id check rejects them.- (["demo-ext\n"], r"Invalid requires\.extensions\[0\]\.id"),- ([{"id": "demo-ext\n"}], r"Invalid requires\.extensions\[0\]\.id"),- (["demo\next"], r"Invalid requires\.extensions\[0\]\.id"),- ],- )- def test_requires_extensions_rejects_malformed(- self, temp_dir, valid_pack_data, bad, expected- ):- """Malformed dependency declarations fail as PresetValidationError.-- Same reasoning as requires.speckit_version: an unvalidated value reaches- ``SpecifierSet`` or ``re.match`` later and surfaces as a bare TypeError- that no caller handles as a malformed manifest.- """- valid_pack_data["requires"]["extensions"] = bad- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match=expected):- PresetManifest(manifest_path)---# ===== PresetRegistry Tests =====---class TestPresetRegistry:- """Test PresetRegistry operations."""-- def test_empty_registry(self, temp_dir):- """Test empty registry initialization."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)- assert registry.list() == {}- assert not registry.is_installed("test-pack")-- def test_load_starts_fresh_for_non_utf8_registry(self, temp_dir):- """A registry file with undecodable bytes must start fresh, not raise.+ # Resolve β pack template should win over core+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Custom Spec Template" in result.read_text()- ``_load()`` already treats malformed JSON as "corrupted registry,- start fresh", but a registry whose *bytes* cannot be decoded as UTF-8- raised a raw ``UnicodeDecodeError`` from the same boundary β the same- corruption class reaching a different exception type.- """- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- (packs_dir / PresetRegistry.REGISTRY_FILE).write_bytes(- b"\xff\xfe not utf-8 \xc3\x28"- )+ # Remove+ manager.remove("test-pack")- registry = PresetRegistry(packs_dir)-- assert registry.data == {- "schema_version": PresetRegistry.SCHEMA_VERSION,- "presets": {},- }-- def test_add_and_get(self, temp_dir):- """Test adding and retrieving a pack."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("test-pack", {"version": "1.0.0", "source": "local"})- assert registry.is_installed("test-pack")-- metadata = registry.get("test-pack")- assert metadata is not None- assert metadata["version"] == "1.0.0"- assert "installed_at" in metadata-- def test_remove(self, temp_dir):- """Test removing a pack."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("test-pack", {"version": "1.0.0"})- assert registry.is_installed("test-pack")-- registry.remove("test-pack")- assert not registry.is_installed("test-pack")-- def test_remove_nonexistent(self, temp_dir):- """Test removing a pack that doesn't exist."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)- registry.remove("nonexistent") # Should not raise-- def test_list(self, temp_dir):- """Test listing all packs."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-a", {"version": "1.0.0"})- registry.add("pack-b", {"version": "2.0.0"})-- all_packs = registry.list()- assert len(all_packs) == 2- assert "pack-a" in all_packs- assert "pack-b" in all_packs-- def test_persistence(self, temp_dir):- """Test that registry data persists across instances."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()-- # Add with first instance- registry1 = PresetRegistry(packs_dir)- registry1.add("test-pack", {"version": "1.0.0"})-- # Load with second instance- registry2 = PresetRegistry(packs_dir)- assert registry2.is_installed("test-pack")-- def test_corrupted_registry(self, temp_dir):- """Test recovery from corrupted registry file."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()-- registry_file = packs_dir / ".registry"- registry_file.write_text("not valid json{{{")-- registry = PresetRegistry(packs_dir)- assert registry.list() == {}-- def test_get_nonexistent(self, temp_dir):- """Test getting a nonexistent pack."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)- assert registry.get("nonexistent") is None-- def test_restore(self, temp_dir):- """Test restore() preserves timestamps exactly."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- # Create original entry with a specific timestamp- original_metadata = {- "version": "1.0.0",- "source": "local",- "installed_at": "2025-01-15T10:30:00+00:00",- "enabled": True,- }- registry.restore("test-pack", original_metadata)-- # Verify exact restoration- restored = registry.get("test-pack")- assert restored["installed_at"] == "2025-01-15T10:30:00+00:00"- assert restored["version"] == "1.0.0"- assert restored["enabled"] is True-- def test_restore_rejects_none_metadata(self, temp_dir):- """Test restore() raises ValueError for None metadata."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- with pytest.raises(ValueError, match="metadata must be a dict"):- registry.restore("test-pack", None)-- def test_restore_rejects_non_dict_metadata(self, temp_dir):- """Test restore() raises ValueError for non-dict metadata."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- with pytest.raises(ValueError, match="metadata must be a dict"):- registry.restore("test-pack", "not-a-dict")-- with pytest.raises(ValueError, match="metadata must be a dict"):- registry.restore("test-pack", ["list", "not", "dict"])-- def test_restore_uses_deep_copy(self, temp_dir):- """Test restore() deep copies metadata to prevent mutation."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- original_metadata = {- "version": "1.0.0",- "nested": {"key": "original"},- }- registry.restore("test-pack", original_metadata)-- # Mutate the original metadata after restore- original_metadata["version"] = "MUTATED"- original_metadata["nested"]["key"] = "MUTATED"-- # Registry should have the original values- stored = registry.get("test-pack")- assert stored["version"] == "1.0.0"- assert stored["nested"]["key"] == "original"-- def test_get_returns_deep_copy(self, temp_dir):- """Test that get() returns a deep copy to prevent mutation."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("test-pack", {"version": "1.0.0", "nested": {"key": "original"}})-- # Get and mutate the returned copy- metadata = registry.get("test-pack")- metadata["version"] = "MUTATED"- metadata["nested"]["key"] = "MUTATED"-- # Original should be unchanged- fresh = registry.get("test-pack")- assert fresh["version"] == "1.0.0"- assert fresh["nested"]["key"] == "original"-- def test_get_returns_none_for_corrupted_entry(self, temp_dir):- """Test that get() returns None for corrupted (non-dict) entries."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- # Directly corrupt the registry with non-dict entries- registry.data["presets"]["corrupted-string"] = "not a dict"- registry.data["presets"]["corrupted-list"] = ["not", "a", "dict"]- registry.data["presets"]["corrupted-int"] = 42- registry._save()-- # All corrupted entries should return None- assert registry.get("corrupted-string") is None- assert registry.get("corrupted-list") is None- assert registry.get("corrupted-int") is None- # Non-existent should also return None- assert registry.get("nonexistent") is None-- def test_list_returns_deep_copy(self, temp_dir):- """Test that list() returns deep copies to prevent mutation."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("test-pack", {"version": "1.0.0", "nested": {"key": "original"}})-- # Get list and mutate- all_packs = registry.list()- all_packs["test-pack"]["version"] = "MUTATED"- all_packs["test-pack"]["nested"]["key"] = "MUTATED"-- # Original should be unchanged- fresh = registry.get("test-pack")- assert fresh["version"] == "1.0.0"- assert fresh["nested"]["key"] == "original"-- def test_list_returns_empty_dict_for_corrupted_registry(self, temp_dir):- """Test that list() returns empty dict when presets is not a dict."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- # Corrupt the registry - presets is a list instead of dict- registry.data["presets"] = ["not", "a", "dict"]- registry._save()-- # list() should return empty dict, not crash- result = registry.list()- assert result == {}-- def test_list_by_priority_excludes_disabled(self, temp_dir):- """Test that list_by_priority excludes disabled presets by default."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-enabled", {"version": "1.0.0", "enabled": True, "priority": 5})- registry.add("pack-disabled", {"version": "1.0.0", "enabled": False, "priority": 1})- registry.add("pack-default", {"version": "1.0.0", "priority": 10}) # no enabled field = True-- # Default: exclude disabled- by_priority = registry.list_by_priority()- pack_ids = [p[0] for p in by_priority]- assert "pack-enabled" in pack_ids- assert "pack-default" in pack_ids- assert "pack-disabled" not in pack_ids-- def test_list_by_priority_includes_disabled_when_requested(self, temp_dir):- """Test that list_by_priority includes disabled presets when requested."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-enabled", {"version": "1.0.0", "enabled": True, "priority": 5})- registry.add("pack-disabled", {"version": "1.0.0", "enabled": False, "priority": 1})-- # Include disabled- by_priority = registry.list_by_priority(include_disabled=True)- pack_ids = [p[0] for p in by_priority]- assert "pack-enabled" in pack_ids- assert "pack-disabled" in pack_ids- # Disabled pack has lower priority number, so it comes first when included- assert pack_ids[0] == "pack-disabled"---# ===== PresetManager Tests =====---def test_unreadable_constitution_provenance_fails_closed(- project_dir, monkeypatch-):- from specify_cli.presets import _constitution_provenance_matches_preset-- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- memory.write_text("# Constitution\n", encoding="utf-8")- provenance = memory.parent / ".constitution-template.json"- provenance.write_text("{}", encoding="utf-8")- real_read_text = Path.read_text-- def unreadable(path, *args, **kwargs):- if path == provenance:- raise OSError("simulated read failure")- return real_read_text(path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", unreadable)-- assert not _constitution_provenance_matches_preset(- project_dir, memory, "example", "1.0.0"- )+ # Resolve β should fall back to core+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Core Spec Template" in result.read_text()+ def test_override_beats_pack_beats_extension_beats_core(self, project_dir, pack_dir):+ """Test the full priority stack: override > pack > extension > core."""+ resolver = PresetResolver(project_dir)-class TestPresetManager:- """Test PresetManager installation and removal."""+ # Core should resolve+ result = resolver.resolve_with_source("spec-template")+ assert result["source"] == "core"- def test_install_from_directory(self, project_dir, pack_dir):- """Test installing a preset from a directory."""- manager = PresetManager(project_dir)- manifest = manager.install_from_directory(pack_dir, "0.1.5")+ # Add extension template+ ext_dir = project_dir / ".specify" / "extensions" / "my-ext"+ ext_templates_dir = ext_dir / "templates"+ ext_templates_dir.mkdir(parents=True)+ (ext_templates_dir / "spec-template.md").write_text("# Extension\n")- assert manifest.id == "test-pack"- assert manager.registry.is_installed("test-pack")+ # Register extension in registry+ extensions_dir = project_dir / ".specify" / "extensions"+ ext_registry = ExtensionRegistry(extensions_dir)+ ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})- # Verify files are copied- installed_dir = project_dir / ".specify" / "presets" / "test-pack"- assert installed_dir.exists()- assert (installed_dir / "preset.yml").exists()- assert (installed_dir / "templates" / "spec-template.md").exists()+ result = resolver.resolve_with_source("spec-template")+ assert result["source"] == "extension:my-ext v1.0.0"- def test_install_already_installed(self, project_dir, pack_dir):- """Test installing an already-installed pack raises error."""+ # Install pack β should win over extensionmanager = PresetManager(project_dir)manager.install_from_directory(pack_dir, "0.1.5")- with pytest.raises(PresetError, match="already installed"):- manager.install_from_directory(pack_dir, "0.1.5")+ result = resolver.resolve_with_source("spec-template")+ assert "test-pack" in result["source"]- def test_install_incompatible(self, project_dir, temp_dir, valid_pack_data):- """Test installing an incompatible pack raises error."""- valid_pack_data["requires"]["speckit_version"] = ">=99.0.0"- incompat_dir = temp_dir / "incompat-pack"- incompat_dir.mkdir()- manifest_path = incompat_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- (incompat_dir / "templates").mkdir()- (incompat_dir / "templates" / "spec-template.md").write_text("test")+ # Add override β should win over pack+ overrides_dir = project_dir / ".specify" / "templates" / "overrides"+ overrides_dir.mkdir(parents=True)+ (overrides_dir / "spec-template.md").write_text("# Override\n")- manager = PresetManager(project_dir)- with pytest.raises(PresetCompatibilityError):- manager.install_from_directory(incompat_dir, "0.1.5")+ result = resolver.resolve_with_source("spec-template")+ assert result["source"] == "project override"- def test_install_from_zip(self, project_dir, pack_dir, temp_dir):- """Test installing from a ZIP file."""+ def test_install_from_zip_then_resolve(self, project_dir, pack_dir, temp_dir):+ """Test installing from ZIP and then resolving."""+ # Create ZIPzip_path = temp_dir / "test-pack.zip"with zipfile.ZipFile(zip_path, 'w') as zf:for file_path in pack_dir.rglob('*'):@@ -871,11805 +101,507 @@ class TestPresetManager:arcname = file_path.relative_to(pack_dir)zf.write(file_path, arcname)+ # Installmanager = PresetManager(project_dir)- manifest = manager.install_from_zip(- zip_path, "0.1.5", catalog_name="preset-catalog"- )- assert manifest.id == "test-pack"- assert manager.registry.is_installed("test-pack")- assert manager.registry.get("test-pack")["source"] == {- "kind": "catalog",- "catalog": "preset-catalog",- }-- def test_install_from_zip_forwards_force(- self, project_dir, pack_dir, temp_dir- ):- """The compatibility wrapper must retain forced reinstall behavior."""- zip_path = temp_dir / "test-pack.zip"- with zipfile.ZipFile(zip_path, "w") as zf:- for file_path in pack_dir.rglob("*"):- if file_path.is_file():- zf.write(file_path, file_path.relative_to(pack_dir))-- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")- manifest = manager.install_from_zip(- zip_path,- "0.1.5",- force=True,- )-- assert manifest.id == "test-pack"- assert manager.registry.is_installed("test-pack")-- def test_install_from_zip_nested(self, project_dir, pack_dir, temp_dir):- """Test installing from ZIP with nested directory."""- zip_path = temp_dir / "test-pack.zip"- with zipfile.ZipFile(zip_path, 'w') as zf:- for file_path in pack_dir.rglob('*'):- if file_path.is_file():- arcname = Path("test-pack-v1.0.0") / file_path.relative_to(pack_dir)- zf.write(file_path, arcname)+ manager.install_from_zip(zip_path, "0.1.5")- manager = PresetManager(project_dir)- manifest = manager.install_from_zip(zip_path, "0.1.5")- assert manifest.id == "test-pack"+ # Resolve+ resolver = PresetResolver(project_dir)+ result = resolver.resolve("spec-template")+ assert result is not None+ assert "Custom Spec Template" in result.read_text()- def test_install_from_zip_no_manifest(self, project_dir, temp_dir):- """Test installing from ZIP without manifest raises error."""- zip_path = temp_dir / "bad.zip"- with zipfile.ZipFile(zip_path, 'w') as zf:- zf.writestr("readme.txt", "no manifest here")- manager = PresetManager(project_dir)- with pytest.raises(PresetValidationError, match="No preset.yml found"):- manager.install_from_zip(zip_path, "0.1.5")-- def test_install_from_zip_rejects_symlink_entry(- self, project_dir, pack_dir, temp_dir- ):- """Preset ZIPs delegate to the shared symlink-safe extractor."""- import stat-- zip_path = temp_dir / "symlink-preset.zip"- link = zipfile.ZipInfo("templates/escape")- link.create_system = 3- link.external_attr = (stat.S_IFLNK | 0o777) << 16- with zipfile.ZipFile(zip_path, "w") as zf:- for file_path in pack_dir.rglob("*"):- if file_path.is_file():- zf.write(file_path, file_path.relative_to(pack_dir))- zf.writestr(link, "../../outside")+class TestSelfTestPreset:+ """Bundled self-test preset contents and catalog visibility."""- manager = PresetManager(project_dir)- with pytest.raises(PresetValidationError, match="Unsafe symlink"):- manager.install_from_zip(zip_path, "0.1.5")-- assert not manager.registry.is_installed("test-pack")-- @pytest.mark.parametrize("suffix", [".tar.gz", ".tgz"])- @pytest.mark.parametrize("nested", [False, True])- def test_install_from_tar_archive(- self, project_dir, pack_dir, temp_dir, suffix, nested- ):- """Tar archives install with the same flat/nested behavior as ZIP."""- archive_path = temp_dir / f"test-pack{suffix}"- with tarfile.open(archive_path, "w:gz") as archive:- for file_path in pack_dir.rglob("*"):- if file_path.is_file():- relative = file_path.relative_to(pack_dir)- arcname = Path("test-pack-v1") / relative if nested else relative- archive.add(file_path, arcname=arcname)+ def test_self_test_preset_exists(self):+ """Verify the self-test preset directory and manifest exist."""+ assert SELF_TEST_PRESET_DIR.exists()+ assert (SELF_TEST_PRESET_DIR / "preset.yml").exists()- manager = PresetManager(project_dir)- manifest = manager.install_from_archive(- archive_path, "0.1.5", catalog_name="preset-catalog"- )+ def test_self_test_manifest_valid(self):+ """Verify the self-test preset manifest is valid."""+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")+ assert manifest.id == "self-test"+ assert manifest.name == "Self-Test Preset"+ assert manifest.version == "1.0.0"+ assert len(manifest.templates) == 7 # 5 templates + 2 commands- assert manifest.id == "test-pack"- assert manager.registry.is_installed("test-pack")- assert manager.registry.get("test-pack")["source"] == {- "kind": "catalog",- "catalog": "preset-catalog",- }-- def test_install_from_tar_rejects_symlink_entry(- self, project_dir, pack_dir, temp_dir- ):- archive_path = temp_dir / "symlink-preset.tar.gz"- with tarfile.open(archive_path, "w:gz") as archive:- for file_path in pack_dir.rglob("*"):- if file_path.is_file():- archive.add(file_path, arcname=file_path.relative_to(pack_dir))- link = tarfile.TarInfo("templates/escape")- link.type = tarfile.SYMTYPE- link.linkname = "../../outside"- archive.addfile(link)+ def test_self_test_provides_all_core_templates(self):+ """Verify the self-test preset provides an override for every core template."""+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")+ provided_names = {t["name"] for t in manifest.templates}+ for name in CORE_TEMPLATE_NAMES:+ assert name in provided_names, f"Self-test preset missing template: {name}"- manager = PresetManager(project_dir)- with pytest.raises(PresetValidationError, match="Unsafe symlink"):- manager.install_from_archive(archive_path, "0.1.5")+ def test_self_test_template_files_exist(self):+ """Verify that all declared template files actually exist on disk."""+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")+ for tmpl in manifest.templates:+ tmpl_path = SELF_TEST_PRESET_DIR / tmpl["file"]+ assert tmpl_path.exists(), f"Missing template file: {tmpl['file']}"- assert not manager.registry.is_installed("test-pack")+ def test_self_test_templates_have_marker(self):+ """Verify each template contains the preset:self-test marker."""+ for name in CORE_TEMPLATE_NAMES:+ tmpl_path = SELF_TEST_PRESET_DIR / "templates" / f"{name}.md"+ content = tmpl_path.read_text()+ assert "preset:self-test" in content, f"{name}.md missing preset:self-test marker"- def test_remove(self, project_dir, pack_dir):- """Test removing a preset."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")- assert manager.registry.is_installed("test-pack")+ def test_self_test_not_in_catalog(self):+ """Verify the self-test preset is NOT in the catalog (it's local-only)."""+ catalog_path = Path(__file__).parent.parent / "presets" / "catalog.json"+ catalog_data = json.loads(catalog_path.read_text())+ assert "self-test" not in catalog_data["presets"]- result = manager.remove("test-pack")- assert result is True- assert not manager.registry.is_installed("test-pack")+ def test_self_test_has_command(self):+ """Verify the self-test preset includes a command override."""+ manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")+ commands = [t for t in manifest.templates if t["type"] == "command"]+ assert len(commands) >= 1+ assert commands[0]["name"] == "speckit.specify"- installed_dir = project_dir / ".specify" / "presets" / "test-pack"- assert not installed_dir.exists()+ def test_self_test_command_file_exists(self):+ """Verify the self-test command file exists on disk."""+ cmd_path = SELF_TEST_PRESET_DIR / "commands" / "speckit.specify.md"+ assert cmd_path.exists()+ content = cmd_path.read_text()+ assert "preset:self-test" in content- def test_remove_nonexistent(self, project_dir):- """Test removing a pack that doesn't exist."""- manager = PresetManager(project_dir)- result = manager.remove("nonexistent")- assert result is False- def test_list_installed(self, project_dir, pack_dir):- """Test listing installed packs."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+class TestInitOptions:+ """Tests for save_init_options / load_init_options helpers."""- installed = manager.list_installed()- assert len(installed) == 1- assert installed[0]["id"] == "test-pack"- assert installed[0]["name"] == "Test Preset"- assert installed[0]["version"] == "1.0.0"- assert installed[0]["template_count"] == 1+ def test_save_and_load_round_trip(self, project_dir):+ from specify_cli import save_init_options, load_init_options- def test_list_installed_empty(self, project_dir):- """Test listing when no packs installed."""- manager = PresetManager(project_dir)- assert manager.list_installed() == []+ opts = {"ai": "claude", "ai_skills": True, "here": False}+ save_init_options(project_dir, opts)- def test_get_pack(self, project_dir, pack_dir):- """Test getting a specific installed pack."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ loaded = load_init_options(project_dir)+ assert loaded["ai"] == "claude"+ assert loaded["ai_skills"] is True- pack = manager.get_pack("test-pack")- assert pack is not None- assert pack.id == "test-pack"+ def test_save_and_load_available_from_init_options_module(self, project_dir):+ from specify_cli._init_options import load_init_options, save_init_options- def test_get_pack_not_installed(self, project_dir):- """Test getting a non-installed pack returns None."""- manager = PresetManager(project_dir)- assert manager.get_pack("nonexistent") is None-- def test_check_compatibility_valid(self, pack_dir, temp_dir):- """Test compatibility check with valid version."""- manager = PresetManager(temp_dir)- manifest = PresetManifest(pack_dir / "preset.yml")- assert manager.check_compatibility(manifest, "0.1.5") is True-- def test_check_compatibility_prerelease(self, pack_dir, temp_dir):- """Test compatibility check allows prereleases and fails on boundary."""- manager = PresetManager(temp_dir)- manifest = PresetManifest(pack_dir / "preset.yml")- # manifest requires >=0.1.0- assert manager.check_compatibility(manifest, "0.8.8.dev0") is True- with pytest.raises(PresetCompatibilityError, match="Preset requires spec-kit"):- manager.check_compatibility(manifest, "0.1.0.dev0")-- def test_check_compatibility_invalid(self, pack_dir, temp_dir):- """Test compatibility check with invalid specifier."""- manager = PresetManager(temp_dir)- manifest = PresetManifest(pack_dir / "preset.yml")- manifest.data["requires"]["speckit_version"] = "not-a-specifier"- with pytest.raises(PresetCompatibilityError, match="Invalid version specifier"):- manager.check_compatibility(manifest, "0.1.5")+ opts = {"ai": "codex", "ai_skills": True, "script": "sh"}+ save_init_options(project_dir, opts)- @pytest.mark.parametrize(- "bad",- [1.0, 5, True, None, [">=0.1.0"], {"min": "0.1"}],- )- def test_check_compatibility_non_string_specifier(self, pack_dir, temp_dir, bad):- """check_compatibility() must report a non-string as a compatibility error.-- Defense in depth for the validator check: this method is public and the- specifier is read back out of mutable manifest data, and ``except- InvalidSpecifier`` does not cover a non-string. Without the guard, scalars- raise a bare TypeError and iterables construct fine only to break inside- .contains() -- neither is a PresetCompatibilityError, so both bypass the- CLI's "Compatibility Error" handler and exit 1 with a raw traceback.- """- manager = PresetManager(temp_dir)- manifest = PresetManifest(pack_dir / "preset.yml")- manifest.data["requires"]["speckit_version"] = bad- with pytest.raises(PresetCompatibilityError, match="Invalid version specifier"):- manager.check_compatibility(manifest, "0.1.5")-- def test_install_with_priority(self, project_dir, pack_dir):- """Test installing a pack with custom priority."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5", priority=5)+ assert load_init_options(project_dir) == opts- metadata = manager.registry.get("test-pack")- assert metadata is not None- assert metadata["priority"] == 5+ def test_save_uses_utf8_encoding(self, project_dir, monkeypatch):+ from specify_cli import save_init_options- def test_install_default_priority(self, project_dir, pack_dir):- """Test that default priority is 10."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ original_write_text = Path.write_text+ seen: dict[str, str | None] = {}- metadata = manager.registry.get("test-pack")- assert metadata is not None- assert metadata["priority"] == 10+ def spy_write_text(path, data, *args, **kwargs):+ if path == project_dir / ".specify" / "init-options.json":+ seen["encoding"] = kwargs.get("encoding")+ return original_write_text(path, data, *args, **kwargs)- def test_list_installed_includes_priority(self, project_dir, pack_dir):- """Test that list_installed includes priority."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5", priority=3)+ monkeypatch.setattr(Path, "write_text", spy_write_text)- installed = manager.list_installed()- assert len(installed) == 1- assert installed[0]["priority"] == 3+ save_init_options(project_dir, {"label": "δΈζζ΅θ―"})+ assert seen["encoding"] == "utf-8"-class TestPresetExtensionDependencies:- """Test find_unmet_extension_dependencies (issue #4231)."""+ def test_load_uses_utf8_encoding(self, project_dir, monkeypatch):+ from specify_cli import load_init_options- @staticmethod- def _install_extension(- project_dir, extension_id, version, enabled=True, with_files=True- ):- """Register an installed extension the way the extension installer does.+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.write_text('{"ai": "codex"}', encoding="utf-8")- ``with_files=False`` leaves the registry entry without its directory,- reproducing the stale state left behind when the files are deleted out- from under the registry.- """- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True, exist_ok=True)- if with_files:- (extensions_dir / extension_id).mkdir(parents=True, exist_ok=True)- registry_path = extensions_dir / ".registry"- data = {"schema_version": "1.0", "extensions": {}}- if registry_path.exists():- data = json.loads(registry_path.read_text(encoding="utf-8"))- data["extensions"][extension_id] = {"version": version, "enabled": enabled}- registry_path.write_text(json.dumps(data), encoding="utf-8")-- @staticmethod- def _manifest(temp_dir, valid_pack_data, declared):- valid_pack_data["requires"]["extensions"] = declared- manifest_path = temp_dir / "dep-preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- return PresetManifest(manifest_path)-- def test_no_declared_dependencies_is_satisfied(- self, project_dir, temp_dir, valid_pack_data- ):- """A preset declaring nothing never reports an unmet dependency."""- manifest_path = temp_dir / "plain-preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)+ original_read_text = Path.read_text+ seen: dict[str, str | None] = {}- manager = PresetManager(project_dir)- assert manager.find_unmet_extension_dependencies(- PresetManifest(manifest_path)- ) == []-- def test_missing_dependency_is_reported(- self, project_dir, temp_dir, valid_pack_data- ):- """An uninstalled required extension is reported as missing."""- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert len(unmet) == 1- assert unmet[0]["id"] == "speckit-inventory"- assert unmet[0]["reason"] == "missing"- assert unmet[0]["installed"] is None-- def test_installed_dependency_is_satisfied(- self, project_dir, temp_dir, valid_pack_data- ):- """An installed extension with no version constraint is satisfied."""- self._install_extension(project_dir, "speckit-inventory", "0.1.0")- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []-- def test_satisfied_version_constraint(- self, project_dir, temp_dir, valid_pack_data- ):- """A satisfied version constraint reports nothing."""- self._install_extension(project_dir, "speckit-inventory", "1.5.0")- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=1.2.0"}],- )+ def spy_read_text(path, *args, **kwargs):+ if path == opts_file:+ seen["encoding"] = kwargs.get("encoding")+ return original_read_text(path, *args, **kwargs)- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []-- def test_unsatisfied_version_constraint_reports_both_versions(- self, project_dir, temp_dir, valid_pack_data- ):- """A version mismatch reports the installed version alongside the constraint."""- self._install_extension(project_dir, "speckit-inventory", "0.1.0")- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=9.0.0"}],- )+ monkeypatch.setattr(Path, "read_text", spy_read_text)- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)+ assert load_init_options(project_dir) == {"ai": "codex"}+ assert seen["encoding"] == "utf-8"- assert len(unmet) == 1- assert unmet[0]["reason"] == "version"- assert unmet[0]["installed"] == "0.1.0"- assert unmet[0]["version"] == ">=9.0.0"+ def test_load_returns_empty_when_missing(self, project_dir):+ from specify_cli import load_init_options+ assert load_init_options(project_dir) == {}- def test_optional_dependency_is_never_reported(- self, project_dir, temp_dir, valid_pack_data- ):- """`required: false` opts out of the warning even when absent."""- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "required": False}],- )+ def test_load_returns_empty_on_invalid_json(self, project_dir):+ from specify_cli import load_init_options- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.write_text("{bad json")- @pytest.mark.parametrize("bad_version", [None, 5, "unknown", "", "latest"])- def test_uncomparable_registry_version_is_not_a_mismatch(- self, project_dir, temp_dir, valid_pack_data, bad_version- ):- """A version that cannot be evaluated must not be reported as a mismatch.+ assert load_init_options(project_dir) == {}- ``version_satisfies()`` returns False for an unparseable version, which- is indistinguishable from a genuine mismatch -- so a string like- "unknown" would otherwise be reported as failing a constraint nobody- can actually evaluate it against.- """- self._install_extension(project_dir, "speckit-inventory", "0.1.0")- registry_path = project_dir / ".specify" / "extensions" / ".registry"- data = json.loads(registry_path.read_text(encoding="utf-8"))- data["extensions"]["speckit-inventory"]["version"] = bad_version- registry_path.write_text(json.dumps(data), encoding="utf-8")-- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=9.0.0"}],- )-- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []-- def test_unregistered_extension_on_disk_is_satisfied(- self, project_dir, temp_dir, valid_pack_data- ):- """A directory with no registry entry still resolves, so it is not missing.-- ``_get_all_extensions_by_priority`` admits safe unregistered- directories at implicit priority 10, so the preset works -- warning- that the dependency is absent would be a false alarm.- """- (project_dir / ".specify" / "extensions" / "speckit-inventory").mkdir(- parents=True- )- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []-- def test_unregistered_extension_cannot_be_version_checked(- self, project_dir, temp_dir, valid_pack_data- ):- """No registry entry means no recorded version, so nothing to compare."""- (project_dir / ".specify" / "extensions" / "speckit-inventory").mkdir(- parents=True- )- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=9.0.0"}],- )-- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []-- def test_corrupted_registry_entry_with_directory_is_not_satisfied(- self, project_dir, temp_dir, valid_pack_data- ):- """A corrupted entry keeps its id registered, so its directory is excluded.-- ``get()`` returns None for a non-dict entry just as it does for an- absent one, but ``keys()`` retains the id specifically so resolution- does not re-admit the directory as an unregistered extension. The- fallback must not revive what resolution excludes.- """- extensions_dir = project_dir / ".specify" / "extensions"- (extensions_dir / "speckit-inventory").mkdir(parents=True)- (extensions_dir / ".registry").write_text(- json.dumps(- {"schema_version": "1.0", "extensions": {"speckit-inventory": "corrupt"}}- ),- encoding="utf-8",- )- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- # Reported as corrupt rather than missing: the id is still registered,- # so a plain `extension add` would be refused as already installed.- assert [dep["reason"] for dep in unmet] == ["corrupt"]----- def test_unregistered_extension_with_corrupt_registry_is_missing(- self, project_dir, temp_dir, valid_pack_data- ):- """A corrupt registry makes resolution fail closed, so it is not usable."""- extensions_dir = project_dir / ".specify" / "extensions"- (extensions_dir / "speckit-inventory").mkdir(parents=True)- (extensions_dir / ".registry").write_text("{not valid json", encoding="utf-8")- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["reason"] for dep in unmet] == ["missing"]-- def test_corrupted_entry_gets_a_forced_reinstall_remedy(- self, project_dir, temp_dir, valid_pack_data- ):- """A corrupted entry is not simply absent: `add <id>` would be refused.-- ``get()`` returns None for it, but ``is_installed()`` still counts the- key, so a plain add reports "already installed". It needs --force.- """- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True)- (extensions_dir / ".registry").write_text(- json.dumps(- {"schema_version": "1.0", "extensions": {"speckit-inventory": "bad"}}- ),- encoding="utf-8",- )- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["reason"] for dep in unmet] == ["corrupt"]--- def test_unreadable_registry_does_not_raise(- self, project_dir, temp_dir, valid_pack_data, monkeypatch- ):- """An OSError from the registry must not crash an already-completed install.-- ``_load()`` lets OSError through, and ``preset_add`` only handles- preset-domain errors, so raising here would turn a finished install- into a traceback over what is only a warning.- """- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- import specify_cli.presets as presets_mod-- def _boom(*args, **kwargs):- raise PermissionError("registry unreadable")-- monkeypatch.setattr(presets_mod, "ExtensionRegistry", _boom)-- assert PresetManager(project_dir).find_unmet_extension_dependencies(- manifest- ) == []---- def test_exact_duplicate_declarations_warn_once(- self, project_dir, temp_dir, valid_pack_data- ):- """Naming the same dependency twice must not print the warning twice."""- manifest = self._manifest(- temp_dir, valid_pack_data, ["speckit-inventory", "speckit-inventory"]- )-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["id"] for dep in unmet] == ["speckit-inventory"]-- def test_same_id_with_different_constraints_is_checked_twice(- self, project_dir, temp_dir, valid_pack_data- ):- """Distinct constraints on one id both have to hold, so both are checked."""- self._install_extension(project_dir, "speckit-inventory", "1.0.0")- manifest = self._manifest(- temp_dir, valid_pack_data,- [- {"id": "speckit-inventory", "version": ">=9.0.0"},- {"id": "speckit-inventory", "version": "<0.5"},- ],- )-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["version"] for dep in unmet] == [">=9.0.0", "<0.5"]-- def test_stale_registry_entry_is_reported(- self, project_dir, temp_dir, valid_pack_data- ):- """A registry entry whose extension directory is gone counts as unmet.-- PresetResolver guards on ``ext_dir.is_dir()`` in both template lookup- and layer collection, so a stale entry contributes nothing -- but the- surviving registry entry would otherwise read as satisfied.- """- self._install_extension(- project_dir, "speckit-inventory", "0.1.0", with_files=False- )- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert len(unmet) == 1- assert unmet[0]["reason"] == "stale"- assert unmet[0]["installed"] == "0.1.0"-- def test_stale_is_reported_ahead_of_disabled_and_version(- self, project_dir, temp_dir, valid_pack_data- ):- """Restoring the files is the prerequisite, so it is reported first."""- self._install_extension(- project_dir, "speckit-inventory", "0.1.0",- enabled=False, with_files=False,- )- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=9.0.0"}],- )-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["reason"] for dep in unmet] == ["stale"]--- def test_disabled_dependency_is_reported(- self, project_dir, temp_dir, valid_pack_data- ):- """A disabled extension contributes nothing, so it counts as unmet.-- Resolution skips disabled extensions, leaving the preset just as inert- as if the extension were absent -- but the registry entry exists, so a- presence-only check would call it satisfied and stay silent.- """- self._install_extension(project_dir, "speckit-inventory", "0.1.0", enabled=False)- manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert len(unmet) == 1- assert unmet[0]["reason"] == "disabled"- assert unmet[0]["installed"] == "0.1.0"-- def test_disabled_is_reported_ahead_of_version_mismatch(- self, project_dir, temp_dir, valid_pack_data- ):- """Enabling is the prerequisite, so it is reported before the version."""- self._install_extension(project_dir, "speckit-inventory", "0.1.0", enabled=False)- manifest = self._manifest(- temp_dir, valid_pack_data,- [{"id": "speckit-inventory", "version": ">=9.0.0"}],- )-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [dep["reason"] for dep in unmet] == ["disabled"]-- def test_multiple_dependencies_report_independently(- self, project_dir, temp_dir, valid_pack_data- ):- """Each declared dependency is evaluated on its own."""- self._install_extension(project_dir, "present-ext", "1.0.0")- self._install_extension(project_dir, "off-ext", "1.0.0", enabled=False)- manifest = self._manifest(- temp_dir, valid_pack_data,- [- "present-ext",- "absent-ext",- "off-ext",- {"id": "opt-ext", "required": False},- ],- )-- unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)-- assert [(dep["id"], dep["reason"]) for dep in unmet] == [- ("absent-ext", "missing"),- ("off-ext", "disabled"),- ]---class TestRegistryPriority:- """Test registry priority sorting."""-- def test_list_by_priority(self, temp_dir):- """Test that list_by_priority sorts by priority number."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-high", {"version": "1.0.0", "priority": 1})- registry.add("pack-low", {"version": "1.0.0", "priority": 20})- registry.add("pack-mid", {"version": "1.0.0", "priority": 10})-- sorted_packs = registry.list_by_priority()- assert len(sorted_packs) == 3- assert sorted_packs[0][0] == "pack-high"- assert sorted_packs[1][0] == "pack-mid"- assert sorted_packs[2][0] == "pack-low"-- def test_list_by_priority_default(self, temp_dir):- """Test that packs without priority default to 10."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-a", {"version": "1.0.0"}) # no priority, defaults to 10- registry.add("pack-b", {"version": "1.0.0", "priority": 5})-- sorted_packs = registry.list_by_priority()- assert sorted_packs[0][0] == "pack-b"- assert sorted_packs[1][0] == "pack-a"-- def test_list_by_priority_invalid_priority_defaults(self, temp_dir):- """Malformed priority values fall back to the default priority."""- packs_dir = temp_dir / "packs"- packs_dir.mkdir()- registry = PresetRegistry(packs_dir)-- registry.add("pack-high", {"version": "1.0.0", "priority": 1})- registry.data["presets"]["pack-invalid"] = {- "version": "1.0.0",- "priority": "high",- }- registry._save()-- sorted_packs = registry.list_by_priority()-- assert [item[0] for item in sorted_packs] == ["pack-high", "pack-invalid"]- assert sorted_packs[1][1]["priority"] == 10---# ===== PresetResolver Tests =====---class TestPresetResolver:- """Test PresetResolver priority stack."""-- def test_resolve_core_template(self, project_dir):- """Test resolving a core template."""- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert result.name == "spec-template.md"- assert "Core Spec Template" in result.read_text()-- def test_resolve_nonexistent(self, project_dir):- """Test resolving a nonexistent template returns None."""- resolver = PresetResolver(project_dir)- result = resolver.resolve("nonexistent-template")- assert result is None-- def test_resolver_ignores_traversing_registry_ids(self, project_dir):- """Registry IDs cannot escape preset or extension install roots."""- for registry_dir, registry_key, outside_name in (- ("presets", "presets", "outside-preset"),- ("extensions", "extensions", "outside-extension"),- ):- outside = project_dir.parent / outside_name- (outside / "templates").mkdir(parents=True)- (outside / "templates" / "spec-template.md").write_text(- f"# Sensitive {registry_key}\n",- encoding="utf-8",- )- installed = project_dir / ".specify" / registry_dir- installed.mkdir(parents=True, exist_ok=True)- (installed / ".registry").write_text(- json.dumps(- {- registry_key: {- f"../../../{outside_name}": {- "enabled": True,- "priority": 1,- }- }- }- ),- encoding="utf-8",- )-- content = PresetResolver(project_dir).resolve_content("spec-template")-- assert content is not None- assert "Core Spec Template" in content- assert "Sensitive" not in content-- def test_resolve_higher_priority_pack_wins(self, project_dir, temp_dir, valid_pack_data):- """Test that a pack with lower priority number wins over higher number."""- manager = PresetManager(project_dir)-- # Create pack A (priority 10 β lower precedence)- pack_a_dir = temp_dir / "pack-a"- pack_a_dir.mkdir()- data_a = {**valid_pack_data}- data_a["preset"] = {**valid_pack_data["preset"], "id": "pack-a", "name": "Pack A"}- with open(pack_a_dir / "preset.yml", 'w') as f:- yaml.dump(data_a, f)- (pack_a_dir / "templates").mkdir()- (pack_a_dir / "templates" / "spec-template.md").write_text("# From Pack A\n")-- # Create pack B (priority 1 β higher precedence)- pack_b_dir = temp_dir / "pack-b"- pack_b_dir.mkdir()- data_b = {**valid_pack_data}- data_b["preset"] = {**valid_pack_data["preset"], "id": "pack-b", "name": "Pack B"}- with open(pack_b_dir / "preset.yml", 'w') as f:- yaml.dump(data_b, f)- (pack_b_dir / "templates").mkdir()- (pack_b_dir / "templates" / "spec-template.md").write_text("# From Pack B\n")-- # Install A first (priority 10), B second (priority 1)- manager.install_from_directory(pack_a_dir, "0.1.5", priority=10)- manager.install_from_directory(pack_b_dir, "0.1.5", priority=1)-- # Pack B should win because lower priority number- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "From Pack B" in result.read_text()-- def test_resolve_override_takes_priority(self, project_dir):- """Test that project overrides take priority over core."""- # Create override- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- override = overrides_dir / "spec-template.md"- override.write_text("# Override Spec Template\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "Override Spec Template" in result.read_text()-- def test_resolve_pack_takes_priority_over_core(self, project_dir, pack_dir):- """Test that installed packs take priority over core templates."""- # Install the pack- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "Custom Spec Template" in result.read_text()-- def _install_pack_with_manifest_file(self, project_dir, *, extra_file=False):- """Create a pack whose manifest declares a NON-convention file: path.-- Returns the pack dir under the project. The declared file lives at- custom/spec.md (not the convention templates/spec-template.md).- """- presets_dir = project_dir / ".specify" / "presets"- pack_dir = presets_dir / "mypack"- (pack_dir / "custom").mkdir(parents=True)- (pack_dir / "custom" / "spec.md").write_text(- "# Manifest-declared Spec\n", encoding="utf-8"- )- if extra_file:- # An undeclared convention-path file the manifest points away from.- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text(- "# Stray Convention Spec\n", encoding="utf-8"- )- manifest = {- "schema_version": "1.0",- "preset": {- "id": "mypack",- "name": "My Pack",- "version": "1.0.0",- "description": "declares a non-convention file path",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "spec-template",- "file": "custom/spec.md",- "strategy": "replace",- }- ]- },- }- with open(pack_dir / "preset.yml", "w") as f:- yaml.dump(manifest, f)- PresetRegistry(presets_dir).add(- "mypack", {"version": "1.0.0", "priority": 10}- )- return pack_dir-- def test_resolve_uses_manifest_declared_file_path(self, project_dir):- """resolve() must honor a manifest-declared non-convention file: path.-- Previously the tier-2 loop was convention-only, so it returned the- core template and resolve_with_source() misattributed source='core',- diverging from collect_all_layers()/resolve_content().- """- pack_dir = self._install_pack_with_manifest_file(project_dir)- resolver = PresetResolver(project_dir)-- result = resolver.resolve("spec-template")- assert result == pack_dir / "custom" / "spec.md"- assert "Manifest-declared Spec" in result.read_text()-- sourced = resolver.resolve_with_source("spec-template")- assert sourced is not None- assert "mypack" in sourced["source"]- # resolve() must agree with collect_all_layers()'s top layer.- layers = resolver.collect_all_layers("spec-template")- assert Path(layers[0]["path"]) == pack_dir / "custom" / "spec.md"-- def test_resolve_manifest_file_wins_over_undeclared_convention_file(- self, project_dir- ):- """A stray convention-path file must not shadow the manifest's file:."""- pack_dir = self._install_pack_with_manifest_file(- project_dir, extra_file=True- )- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result == pack_dir / "custom" / "spec.md"- assert "Manifest-declared Spec" in result.read_text()-- def test_resolve_skips_convention_when_manifest_file_missing(self, project_dir):- """When the manifest declares a file: that does not exist, resolve()- must NOT fall back to a convention file in the same pack (that would- mask a typo) β it skips the pack and resolves core instead."""- presets_dir = project_dir / ".specify" / "presets"- pack_dir = presets_dir / "mypack"- # Manifest declares custom/spec.md (MISSING); a convention file exists- # in the pack and must NOT be used.- (pack_dir / "templates").mkdir(parents=True)- (pack_dir / "templates" / "spec-template.md").write_text(- "# Stray Convention Spec\n", encoding="utf-8"- )- manifest = {- "schema_version": "1.0",- "preset": {- "id": "mypack",- "name": "My Pack",- "version": "1.0.0",- "description": "declares a missing file path",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "spec-template",- "file": "custom/spec.md",- "strategy": "replace",- }- ]- },- }- with open(pack_dir / "preset.yml", "w") as f:- yaml.dump(manifest, f)- PresetRegistry(presets_dir).add(- "mypack", {"version": "1.0.0", "priority": 10}- )-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- content = result.read_text()- assert "Stray Convention Spec" not in content # pack convention skipped- assert "Core Spec Template" in content # fell through to core-- def test_resolve_skips_convention_when_manifest_file_is_directory(- self, project_dir- ):- """When the manifest's file: path resolves to a DIRECTORY (not a regular- file), resolve()/collect_all_layers() must treat it as missing β exists()- would accept it and downstream read_text() on a directory would crash.- The pack is skipped (no convention fallback), so core wins."""- presets_dir = project_dir / ".specify" / "presets"- pack_dir = presets_dir / "mypack"- # Declared file: custom/spec.md is created as a DIRECTORY.- (pack_dir / "custom" / "spec.md").mkdir(parents=True)- # A convention file also exists and must NOT be used.- (pack_dir / "templates").mkdir(parents=True)- (pack_dir / "templates" / "spec-template.md").write_text(- "# Stray Convention Spec\n", encoding="utf-8"- )- manifest = {- "schema_version": "1.0",- "preset": {- "id": "mypack",- "name": "My Pack",- "version": "1.0.0",- "description": "declares a file: that is actually a directory",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "spec-template",- "file": "custom/spec.md",- "strategy": "replace",- }- ]- },- }- with open(pack_dir / "preset.yml", "w") as f:- yaml.dump(manifest, f)- PresetRegistry(presets_dir).add(- "mypack", {"version": "1.0.0", "priority": 10}- )-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert result.is_file() # never a directory- content = result.read_text()- assert "Stray Convention Spec" not in content # pack convention skipped- assert "Core Spec Template" in content # fell through to core- # collect_all_layers() must agree: the directory is not a layer.- layers = resolver.collect_all_layers("spec-template")- assert all(Path(layer["path"]).is_file() for layer in layers)- assert all(- Path(layer["path"]) != pack_dir / "custom" / "spec.md"- for layer in layers- )-- def test_resolve_override_takes_priority_over_pack(self, project_dir, pack_dir):- """Test that overrides take priority over installed packs."""- # Install the pack- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- # Create override- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- override = overrides_dir / "spec-template.md"- override.write_text("# Override Spec Template\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "Override Spec Template" in result.read_text()-- def test_resolve_extension_provided_templates(self, project_dir):- """Test resolving templates provided by extensions."""- # Create extension with templates- ext_dir = project_dir / ".specify" / "extensions" / "my-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "custom-template.md"- ext_template.write_text("# Extension Custom Template\n")-- # Register extension in registry- extensions_dir = project_dir / ".specify" / "extensions"- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})-- resolver = PresetResolver(project_dir)- result = resolver.resolve("custom-template")- assert result is not None- assert "Extension Custom Template" in result.read_text()-- def test_resolve_disabled_extension_templates_skipped(self, project_dir):- """Test that disabled extension templates are not resolved."""- # Create extension with templates- ext_dir = project_dir / ".specify" / "extensions" / "disabled-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "disabled-template.md"- ext_template.write_text("# Disabled Extension Template\n")-- # Register extension as disabled- extensions_dir = project_dir / ".specify" / "extensions"- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("disabled-ext", {"version": "1.0.0", "priority": 1, "enabled": False})-- # Template should NOT be resolved because extension is disabled- resolver = PresetResolver(project_dir)- result = resolver.resolve("disabled-template")- assert result is None, "Disabled extension template should not be resolved"-- def test_resolve_disabled_extension_not_picked_up_as_unregistered(self, project_dir):- """Test that disabled extensions are not picked up via unregistered dir scan."""- # Create extension directory with templates- ext_dir = project_dir / ".specify" / "extensions" / "test-disabled-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "unique-disabled-template.md"- ext_template.write_text("# Should Not Resolve\n")-- # Register the extension but disable it- extensions_dir = project_dir / ".specify" / "extensions"- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("test-disabled-ext", {"version": "1.0.0", "enabled": False})-- # Verify the template is NOT resolved (even though the directory exists)- resolver = PresetResolver(project_dir)- result = resolver.resolve("unique-disabled-template")- assert result is None, "Disabled extension should not be picked up as unregistered"-- @pytest.mark.parametrize(- "registry_bytes",- [b"{ not valid json", b'{"extensions": []}', b"[]"],- ids=["invalid_json", "non_mapping_extensions", "non_mapping_root"],- )- def test_resolve_fails_closed_on_corrupt_extension_registry(- self, project_dir, registry_bytes- ):- """A corrupt extension registry must fail closed rather than let the- directory scan admit every on-disk extension as enabled."""- extensions_dir = project_dir / ".specify" / "extensions"- ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"- ext_templates_dir.mkdir(parents=True)- (ext_templates_dir / "custom-template.md").write_text(- "# Should not be served\n"- )- (extensions_dir / ".registry").write_bytes(registry_bytes)-- resolver = PresetResolver(project_dir)- with pytest.raises(PresetValidationError, match="Invalid extension registry"):- resolver._get_all_extensions_by_priority()- with pytest.raises(PresetValidationError, match="Invalid extension registry"):- resolver.resolve("custom-template")-- def test_resolve_fails_closed_when_registry_is_directory(self, project_dir):- """A directory at the registry path must fail closed, not be treated as- an absent registry that enables every on-disk extension."""- extensions_dir = project_dir / ".specify" / "extensions"- ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"- ext_templates_dir.mkdir(parents=True)- (ext_templates_dir / "custom-template.md").write_text(- "# Should not be served\n"- )- (extensions_dir / ".registry").mkdir()-- resolver = PresetResolver(project_dir)- with pytest.raises(PresetValidationError, match="Invalid extension registry"):- resolver.resolve("custom-template")-- def test_resolve_fails_closed_when_registry_is_broken_symlink(self, project_dir):- """A dangling ``.registry`` symlink must fail closed. ``Path.exists()``- follows symlinks and would mistake it for an absent registry, reopening- the fail-open directory scan."""- extensions_dir = project_dir / ".specify" / "extensions"- ext_templates_dir = extensions_dir / "sneaky-ext" / "templates"- ext_templates_dir.mkdir(parents=True)- (ext_templates_dir / "custom-template.md").write_text(- "# Should not be served\n"- )- (extensions_dir / ".registry").symlink_to(- extensions_dir / "does-not-exist"- )-- registry = ExtensionRegistry(extensions_dir)- assert registry.is_corrupt()- resolver = PresetResolver(project_dir)- with pytest.raises(PresetValidationError, match="Invalid extension registry"):- resolver.resolve("custom-template")-- def test_resolve_pack_over_extension(self, project_dir, pack_dir, temp_dir, valid_pack_data):- """Test that pack templates take priority over extension templates."""- # Create extension with templates- ext_dir = project_dir / ".specify" / "extensions" / "my-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "spec-template.md"- ext_template.write_text("# Extension Spec Template\n")-- # Install a pack with the same template- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- # Pack should win over extension- assert "Custom Spec Template" in result.read_text()-- def test_resolve_with_source_core(self, project_dir):- """Test resolve_with_source for core template."""- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("spec-template")- assert result is not None- assert result["source"] == "core"- assert "spec-template.md" in result["path"]-- def test_resolve_with_source_override(self, project_dir):- """Test resolve_with_source for override template."""- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- override = overrides_dir / "spec-template.md"- override.write_text("# Override\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("spec-template")- assert result is not None- assert result["source"] == "project override"-- def test_resolve_with_source_pack(self, project_dir, pack_dir):- """Test resolve_with_source for pack template."""- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("spec-template")- assert result is not None- assert "test-pack" in result["source"]- assert "v1.0.0" in result["source"]-- def test_resolve_with_source_extension(self, project_dir):- """Test resolve_with_source for extension-provided template."""- ext_dir = project_dir / ".specify" / "extensions" / "my-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "unique-template.md"- ext_template.write_text("# Unique\n")-- # Register extension in registry- extensions_dir = project_dir / ".specify" / "extensions"- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})-- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("unique-template")- assert result is not None- assert result["source"] == "extension:my-ext v1.0.0"-- def test_resolve_with_source_not_found(self, project_dir):- """Test resolve_with_source for nonexistent template."""- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("nonexistent")- assert result is None-- def test_resolve_skips_hidden_extension_dirs(self, project_dir):- """Test that hidden directories in extensions are skipped."""- ext_dir = project_dir / ".specify" / "extensions" / ".backup"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- ext_template = ext_templates_dir / "hidden-template.md"- ext_template.write_text("# Hidden\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve("hidden-template")- assert result is None-- def test_collect_all_layers_finds_bundled_core_without_specify_commands(- self, project_dir- ):- """Tier-5 fallback locates the bundled core command when- .specify/templates/commands/ has no matching file.-- Regression test for #3086: a stale ``.parent`` chain made the- source-checkout fallback resolve to ``src/templates/...`` (which does- not exist), so ``wrap`` presets found no base layer. The fallback must- resolve against the real repo-root ``templates/commands`` tree.- """- # project_dir's commands dir is empty, so tier-4 cannot satisfy this.- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("speckit.implement", "command")- assert layers, "expected a bundled core base layer to be found"- assert layers[-1]["source"] == "core (bundled)"- assert layers[-1]["path"].parts[-2:] == ("commands", "implement.md")-- def test_resolve_command_falls_back_to_bundled_core(self, project_dir):- """resolve() tier-5 returns the bundled core command when- .specify/templates/commands/ lacks it (regression for #3086)."""- resolver = PresetResolver(project_dir)- result = resolver.resolve("speckit.implement", "command")- assert result is not None- assert result.parts[-2:] == ("commands", "implement.md")---class TestResolveCore:- """Test PresetResolver.resolve_core() skips the installed-presets tier."""-- def test_resolve_core_does_not_return_preset_files(self, project_dir):- """resolve_core must not return files from .specify/presets/."""- preset_cmd_dir = project_dir / ".specify" / "presets" / "my-preset" / "commands"- preset_cmd_dir.mkdir(parents=True)- (preset_cmd_dir / "specify.md").write_text("---\ndescription: preset wrap\n---\n\nwrap body\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_core("specify", "command")- # The preset file must never be returned β but the bundled core may be.- if result is not None:- assert "presets" not in result.parts-- def test_resolve_core_returns_core_template(self, project_dir):- """resolve_core falls through to core templates (tier 4)."""- core_cmd_dir = project_dir / ".specify" / "templates" / "commands"- core_cmd_dir.mkdir(parents=True, exist_ok=True)- (core_cmd_dir / "specify.md").write_text("---\ndescription: core\n---\n\ncore body\n")-- # Also place a preset file β resolve_core must still return the core- preset_cmd_dir = project_dir / ".specify" / "presets" / "my-preset" / "commands"- preset_cmd_dir.mkdir(parents=True)- (preset_cmd_dir / "specify.md").write_text("---\ndescription: preset wrap\n---\n\nwrap body\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_core("specify", "command")- assert result is not None- assert "presets" not in result.parts- assert result.parts[-3:] == ("templates", "commands", "specify.md")-- def test_resolve_core_returns_override(self, project_dir):- """resolve_core returns tier-1 override if present."""- override_dir = project_dir / ".specify" / "templates" / "overrides"- override_dir.mkdir(parents=True)- (override_dir / "specify.md").write_text("---\ndescription: override\n---\n\noverride body\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_core("specify", "command")- assert result is not None- assert result.parts[-2:] == ("overrides", "specify.md")-- def test_resolve_core_returns_extension_template(self, project_dir):- """resolve_core returns extension templates (tier 3)."""- ext_cmd_dir = project_dir / ".specify" / "extensions" / "myext" / "commands"- ext_cmd_dir.mkdir(parents=True)- (ext_cmd_dir / "myext-cmd.md").write_text("---\ndescription: ext\n---\n\next body\n")-- resolver = PresetResolver(project_dir)- result = resolver.resolve_core("myext-cmd", "command")- assert result is not None- assert result.parts[-4:-1] == ("extensions", "myext", "commands")-- def test_resolve_core_returns_none_when_nothing_found(self, project_dir):- """resolve_core returns None when no file found in tiers 1/3/4."""- resolver = PresetResolver(project_dir)- result = resolver.resolve_core("nonexistent", "command")- assert result is None-- def test_resolve_extension_command_via_manifest_skips_oserror_manifests(self, project_dir):- """resolve_extension_command_via_manifest skips extensions whose manifest raises OSError."""- import unittest.mock as mock-- ext_dir = project_dir / ".specify" / "extensions" / "bad-ext"- cmd_dir = ext_dir / "commands"- cmd_dir.mkdir(parents=True)- (cmd_dir / "mycmd.md").write_text("---\ndescription: d\n---\n\nbody\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: bad-ext\n name: Bad\n version: 1.0.0\n"- " description: d\n author: a\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n commands:\n"- " - name: speckit.bad-ext.mycmd\n"- " file: commands/mycmd.md\n"- " description: My command\n"- )-- resolver = PresetResolver(project_dir)- # Simulate a permission error when opening the manifest file.- with mock.patch("builtins.open", side_effect=PermissionError("denied")):- result = resolver.resolve_extension_command_via_manifest("speckit.bad-ext.mycmd")-- assert result is None, "OSError during manifest load must be silently skipped"---class TestExtensionPriorityResolution:- """Test extension priority resolution with registered and unregistered extensions."""-- def test_unregistered_beats_registered_with_lower_precedence(self, project_dir):- """Unregistered extension (implicit priority 10) beats registered with priority 20."""- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True, exist_ok=True)-- # Create registered extension with priority 20 (lower precedence than 10)- registered_dir = extensions_dir / "registered-ext"- (registered_dir / "templates").mkdir(parents=True)- (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")-- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 20})-- # Create unregistered extension directory (implicit priority 10)- unregistered_dir = extensions_dir / "unregistered-ext"- (unregistered_dir / "templates").mkdir(parents=True)- (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")-- # Unregistered (priority 10) should beat registered (priority 20)- resolver = PresetResolver(project_dir)- result = resolver.resolve("test-template")- assert result is not None- assert "From Unregistered" in result.read_text()-- def test_registered_with_higher_precedence_beats_unregistered(self, project_dir):- """Registered extension with priority 5 beats unregistered (implicit priority 10)."""- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True, exist_ok=True)-- # Create registered extension with priority 5 (higher precedence than 10)- registered_dir = extensions_dir / "registered-ext"- (registered_dir / "templates").mkdir(parents=True)- (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")-- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 5})-- # Create unregistered extension directory (implicit priority 10)- unregistered_dir = extensions_dir / "unregistered-ext"- (unregistered_dir / "templates").mkdir(parents=True)- (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")-- # Registered (priority 5) should beat unregistered (priority 10)- resolver = PresetResolver(project_dir)- result = resolver.resolve("test-template")- assert result is not None- assert "From Registered" in result.read_text()-- def test_unregistered_attribution_with_priority_ordering(self, project_dir):- """Test resolve_with_source correctly attributes unregistered extension."""- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True, exist_ok=True)-- # Create registered extension with priority 20- registered_dir = extensions_dir / "registered-ext"- (registered_dir / "templates").mkdir(parents=True)- (registered_dir / "templates" / "test-template.md").write_text("# From Registered\n")-- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("registered-ext", {"version": "1.0.0", "priority": 20})-- # Create unregistered extension (implicit priority 10)- unregistered_dir = extensions_dir / "unregistered-ext"- (unregistered_dir / "templates").mkdir(parents=True)- (unregistered_dir / "templates" / "test-template.md").write_text("# From Unregistered\n")-- # Attribution should show unregistered extension- resolver = PresetResolver(project_dir)- result = resolver.resolve_with_source("test-template")- assert result is not None- assert "unregistered-ext" in result["source"]- assert "(unregistered)" in result["source"]-- def test_same_priority_sorted_alphabetically(self, project_dir):- """Extensions with same priority are sorted alphabetically by ID."""- extensions_dir = project_dir / ".specify" / "extensions"- extensions_dir.mkdir(parents=True, exist_ok=True)-- # Create two unregistered extensions (both implicit priority 10)- # "aaa-ext" should come before "zzz-ext" alphabetically- zzz_dir = extensions_dir / "zzz-ext"- (zzz_dir / "templates").mkdir(parents=True)- (zzz_dir / "templates" / "test-template.md").write_text("# From ZZZ\n")-- aaa_dir = extensions_dir / "aaa-ext"- (aaa_dir / "templates").mkdir(parents=True)- (aaa_dir / "templates" / "test-template.md").write_text("# From AAA\n")-- # AAA should win due to alphabetical ordering at same priority- resolver = PresetResolver(project_dir)- result = resolver.resolve("test-template")- assert result is not None- assert "From AAA" in result.read_text()---# ===== PresetCatalog Tests =====---class TestPresetCatalog:- """Test template catalog functionality."""-- def _inject_github_config(self, monkeypatch, token_env="GH_TOKEN"):- from tests.specify_cli.authentication.helpers import inject_github_config- inject_github_config(monkeypatch, token_env)-- def test_default_catalog_url(self, project_dir):- """Test default catalog URL."""- catalog = PresetCatalog(project_dir)- assert catalog.DEFAULT_CATALOG_URL.startswith("https://")- assert catalog.DEFAULT_CATALOG_URL.endswith("/presets/catalog.json")-- def test_community_catalog_url(self, project_dir):- """Test community catalog URL."""- catalog = PresetCatalog(project_dir)- assert "presets/catalog.community.json" in catalog.COMMUNITY_CATALOG_URL-- def test_cache_validation_no_cache(self, project_dir):- """Test cache validation when no cache exists."""- catalog = PresetCatalog(project_dir)- assert catalog.is_cache_valid() is False-- def test_cache_validation_valid(self, project_dir):- """Test cache validation with valid cache."""- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)-- catalog.cache_file.write_text(json.dumps({- "schema_version": "1.0",- "presets": {},- }))- catalog.cache_metadata_file.write_text(json.dumps({- "cached_at": datetime.now(timezone.utc).isoformat(),- }))-- assert catalog.is_cache_valid() is True-- def test_cache_validation_expired(self, project_dir):- """Test cache validation with expired cache."""- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)-- catalog.cache_file.write_text(json.dumps({- "schema_version": "1.0",- "presets": {},- }))- catalog.cache_metadata_file.write_text(json.dumps({- "cached_at": "2020-01-01T00:00:00+00:00",- }))-- assert catalog.is_cache_valid() is False-- def test_cache_validation_corrupted(self, project_dir):- """Test cache validation with corrupted metadata."""- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)-- catalog.cache_file.write_text("not json")- catalog.cache_metadata_file.write_text("not json")-- assert catalog.is_cache_valid() is False-- def test_clear_cache(self, project_dir):- """Test clearing the cache."""- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- catalog.cache_file.write_text("{}")- catalog.cache_metadata_file.write_text("{}")-- catalog.clear_cache()-- assert not catalog.cache_file.exists()- assert not catalog.cache_metadata_file.exists()-- def test_search_with_cached_data(self, project_dir, monkeypatch):- """Test search with cached catalog data."""- from unittest.mock import patch-- monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL", raising=False)- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)-- catalog_data = {- "schema_version": "1.0",- "presets": {- "safe-agile": {- "name": "SAFe Agile Templates",- "description": "SAFe-aligned templates",- "author": "agile-community",- "version": "1.0.0",- "tags": ["safe", "agile"],- },- "healthcare": {- "name": "Healthcare Compliance",- "description": "HIPAA-compliant templates",- "author": "healthcare-org",- "version": "1.0.0",- "tags": ["healthcare", "hipaa"],- },- }- }-- catalog.cache_file.write_text(json.dumps(catalog_data))- catalog.cache_metadata_file.write_text(json.dumps({- "cached_at": datetime.now(timezone.utc).isoformat(),- }))-- # Isolate from community catalog so results are deterministic- default_only = [PresetCatalogEntry(url=catalog.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True)]- with patch.object(catalog, "get_active_catalogs", return_value=default_only):- # Search by query- results = catalog.search(query="agile")- assert len(results) == 1- assert results[0]["id"] == "safe-agile"-- # Search by tag- results = catalog.search(tag="hipaa")- assert len(results) == 1- assert results[0]["id"] == "healthcare"-- # Search by author- results = catalog.search(author="agile-community")- assert len(results) == 1-- # Search all- results = catalog.search()- assert len(results) == 2-- def test_get_pack_info(self, project_dir):- """Test getting info for a specific pack."""- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)-- catalog_data = {- "schema_version": "1.0",- "presets": {- "test-pack": {- "name": "Test Pack",- "version": "1.0.0",- },- }- }-- catalog.cache_file.write_text(json.dumps(catalog_data))- catalog.cache_metadata_file.write_text(json.dumps({- "cached_at": datetime.now(timezone.utc).isoformat(),- }))-- info = catalog.get_pack_info("test-pack")- assert info is not None- assert info["name"] == "Test Pack"- assert info["id"] == "test-pack"-- assert catalog.get_pack_info("nonexistent") is None-- def test_validate_catalog_url_https(self, project_dir):- """Test that HTTPS URLs are accepted."""- catalog = PresetCatalog(project_dir)- catalog._validate_catalog_url("https://example.com/catalog.json")-- def test_validate_catalog_url_http_rejected(self, project_dir):- """Test that HTTP URLs are rejected."""- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="must use HTTPS"):- catalog._validate_catalog_url("http://example.com/catalog.json")-- def test_validate_catalog_url_localhost_http_allowed(self, project_dir):- """Test that HTTP is allowed for localhost."""- catalog = PresetCatalog(project_dir)- catalog._validate_catalog_url("http://localhost:8080/catalog.json")- catalog._validate_catalog_url("http://127.0.0.1:8080/catalog.json")-- @pytest.mark.parametrize(- "url",- [- "https://:8080", # port only, no host- "https://:8080/catalog.json", # port only, with path- "https://:0", # port only, no host- "https://user@", # userinfo only, no host- "https://user:pass@", # userinfo only, no host- ],- )- def test_validate_catalog_url_hostless_rejected(self, project_dir, url):- """Reject host-less URLs whose netloc is truthy but hostname is None (#3209).-- ``urlparse('https://:8080').netloc`` is ``':8080'`` (truthy) but its- ``hostname`` is ``None``, so a netloc-based check would accept a URL- with no actual host, contradicting the "valid URL with a host" error.- """- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="valid URL with a host"):- catalog._validate_catalog_url(url)-- def test_validate_catalog_url_malformed_rejected(self, project_dir):- """A malformed URL raises PresetValidationError, not a raw ValueError.-- ``urlparse('https://[::1').hostname`` raises ``ValueError: Invalid IPv6- URL`` (unterminated bracket). Without wrapping, that leaks past callers'- ``except PresetValidationError`` guards and crashes the CLI. Mirrors the- shared ``CatalogStackBase`` (#3435) and ``IntegrationCatalog`` behaviour.- """- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="malformed"):- catalog._validate_catalog_url("https://[::1")-- def test_validate_catalog_url_out_of_range_port_rejected(self, project_dir):- """An out-of-range port raises ValueError lazily on ``.port`` access.-- ``urlparse(...).hostname`` alone does not validate the port, so- without a ``_ = parsed.port`` probe inside the try/except, a URL like- ``https://example.com:99999/catalog.json`` sails through this- validator and only fails later, at fetch time, with a raw- untranslated error instead of a clean ``PresetValidationError``. The- sibling ``preset add --from <url>`` download-URL guard already- catches this shape (see- ``test_preset_add_from_url_out_of_range_port_exits_cleanly``); this- catalog-source-URL validator had drifted from it and from the- original guard in ``specify_cli.catalogs``/- ``bundler/services/adapters.py``.- """- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="malformed"):- catalog._validate_catalog_url("https://example.com:99999/catalog.json")-- def test_env_var_catalog_url(self, project_dir, monkeypatch):- """Test catalog URL from environment variable."""- monkeypatch.setenv("SPECKIT_PRESET_CATALOG_URL", "https://custom.example.com/catalog.json")- catalog = PresetCatalog(project_dir)- assert catalog.get_catalog_url() == "https://custom.example.com/catalog.json"-- # --- _make_request / GitHub auth ----- def test_make_request_no_token_no_auth_header(self, project_dir, monkeypatch):- """Without a token, requests carry no Authorization header."""- monkeypatch.delenv("GITHUB_TOKEN", raising=False)- monkeypatch.delenv("GH_TOKEN", raising=False)- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")- assert "Authorization" not in req.headers-- def test_make_request_whitespace_only_github_token_ignored(self, project_dir, monkeypatch):- """A whitespace-only GITHUB_TOKEN is treated as unset."""- monkeypatch.setenv("GITHUB_TOKEN", " ")- monkeypatch.delenv("GH_TOKEN", raising=False)- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")- assert "Authorization" not in req.headers-- def test_make_request_whitespace_github_token_falls_back_to_gh_token(self, project_dir, monkeypatch):- """When GITHUB_TOKEN is whitespace-only, GH_TOKEN is used as fallback."""- monkeypatch.setenv("GITHUB_TOKEN", " ")- monkeypatch.setenv("GH_TOKEN", "ghp_fallback")- self._inject_github_config(monkeypatch, token_env="GH_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")- assert req.get_header("Authorization") == "Bearer ghp_fallback"-- def test_make_request_github_token_added_for_github_url(self, project_dir, monkeypatch):- """GITHUB_TOKEN is attached for raw.githubusercontent.com URLs."""- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- monkeypatch.delenv("GH_TOKEN", raising=False)- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://raw.githubusercontent.com/org/repo/main/catalog.json")- assert req.get_header("Authorization") == "Bearer ghp_testtoken"-- def test_make_request_gh_token_fallback(self, project_dir, monkeypatch):- """GH_TOKEN is used when GITHUB_TOKEN is absent."""- monkeypatch.delenv("GITHUB_TOKEN", raising=False)- monkeypatch.setenv("GH_TOKEN", "ghp_ghtoken")- self._inject_github_config(monkeypatch, token_env="GH_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://github.com/org/repo/releases/download/v1/pack.zip")- assert req.get_header("Authorization") == "Bearer ghp_ghtoken"-- def test_make_request_gh_token_takes_precedence(self, project_dir, monkeypatch):- """When auth.json uses GH_TOKEN, that token is used regardless of GITHUB_TOKEN."""- monkeypatch.setenv("GITHUB_TOKEN", "ghp_secondary")- monkeypatch.setenv("GH_TOKEN", "ghp_primary")- self._inject_github_config(monkeypatch, token_env="GH_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://api.github.com/repos/org/repo")- assert req.get_header("Authorization") == "Bearer ghp_primary"-- def test_make_request_token_added_for_codeload_github_com(self, project_dir, monkeypatch):- """GITHUB_TOKEN is attached for codeload.github.com URLs."""- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://codeload.github.com/org/repo/zip/refs/tags/v1.0.0")- assert req.get_header("Authorization") == "Bearer ghp_testtoken"-- def test_make_request_no_auth_for_non_matching_host(self, project_dir, monkeypatch):- """Auth is NOT attached to hosts not listed in auth.json."""- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://internal.example.com/catalog.json")- assert "Authorization" not in req.headers-- def test_make_request_no_auth_when_no_config(self, project_dir, monkeypatch):- """No auth header when no auth.json config exists."""- monkeypatch.delenv("GITHUB_TOKEN", raising=False)- monkeypatch.delenv("GH_TOKEN", raising=False)- catalog = PresetCatalog(project_dir)- req = catalog._make_request("https://github.com/org/repo/releases/download/v1/pack.zip")- assert "Authorization" not in req.headers-- def test_fetch_single_catalog_sends_auth_header(self, project_dir, monkeypatch):- """_fetch_single_catalog passes Authorization header when configured."""- from unittest.mock import patch, MagicMock-- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)-- catalog_data = {"schema_version": "1.0", "presets": {}}- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(catalog_data).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://raw.githubusercontent.com/org/repo/main/presets/catalog.json"-- captured = {}- mock_opener = MagicMock()-- def fake_open(req, timeout=None):- captured["req"] = req- return mock_response-- mock_opener.open.side_effect = fake_open-- entry = PresetCatalogEntry(- url="https://raw.githubusercontent.com/org/repo/main/presets/catalog.json",- name="private",- priority=1,- install_allowed=True,- )-- with patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):- catalog._fetch_single_catalog(entry, force_refresh=True)-- assert captured["req"].get_header("Authorization") == "Bearer ghp_testtoken"-- def test_fetch_single_catalog_revalidates_redirected_url(self, project_dir):- """An HTTPS catalog URL that redirects to http:// must be rejected AFTER- the redirect. _open_url follows redirects (auth stripped on downgrade),- so without re-validating response.geturl() the http payload would still- be fetched and trusted β and it supplies each preset's download_url +- sha256, defeating verify_archive_sha256. Parity with the- integrations/workflows catalog fetchers."""- catalog = PresetCatalog(project_dir)-- class _Resp:- def __enter__(self):- return self-- def __exit__(self, *a):- return False-- def read(self):- return json.dumps({"schema_version": "1.0", "presets": {}}).encode()-- def geturl(self):- return "http://evil.test/catalog.json" # downgraded via redirect-- catalog._open_url = lambda url, timeout=None, redirect_validator=None: _Resp()-- entry = PresetCatalogEntry(- url="https://good.example/catalog.json",- name="c",- priority=1,- install_allowed=True,- )- with pytest.raises(PresetValidationError, match="HTTPS"):- catalog._fetch_single_catalog(entry, force_refresh=True)-- def test_fetch_single_catalog_validates_every_redirect_hop(self, project_dir):- """A redirect_validator is passed to _open_url and rejects a non-HTTPS- INTERMEDIATE hop β closing the https -> http -> attacker-https chain that- a terminal-URL-only check would miss."""- catalog = PresetCatalog(project_dir)- captured = {}-- def fake_open(url, timeout=None, redirect_validator=None):- captured["rv"] = redirect_validator- # Simulate the hop urllib validates before following the redirect.- redirect_validator("https://good.example/catalog.json", "http://evil.test/hop")- raise AssertionError("redirect_validator should have raised")-- catalog._open_url = fake_open- entry = PresetCatalogEntry(- url="https://good.example/catalog.json",- name="c",- priority=1,- install_allowed=True,- )- with pytest.raises(PresetValidationError, match="HTTPS"):- catalog._fetch_single_catalog(entry, force_refresh=True)- assert captured["rv"] is not None-- def test_fetch_catalog_legacy_revalidates_redirected_url(self, project_dir):- """The legacy single-catalog fetch_catalog() path also rejects an- HTTPS -> http redirected payload (final geturl() check), matching- _fetch_single_catalog β it previously parsed the body with no check."""- catalog = PresetCatalog(project_dir)-- class _Resp:- def __enter__(self):- return self-- def __exit__(self, *a):- return False-- def read(self):- return json.dumps({"schema_version": "1.0", "presets": {}}).encode()-- def geturl(self):- return "http://evil.test/catalog.json"-- catalog._open_url = lambda url, timeout=None, redirect_validator=None: _Resp()- with pytest.raises(PresetError, match="HTTPS"):- catalog.fetch_catalog(force_refresh=True)-- def test_fetch_catalog_legacy_validates_every_redirect_hop(self, project_dir):- """The legacy fetch_catalog() path also validates every INTERMEDIATE hop- (not just the terminal URL): it must supply a redirect_validator that- rejects an insecure hop, so an https -> http -> https chain is caught."""- catalog = PresetCatalog(project_dir)- captured = {}-- def fake_open(url, timeout=None, redirect_validator=None):- captured["rv"] = redirect_validator- redirect_validator(url, "http://evil.test/hop")- raise AssertionError("redirect_validator should have raised")-- catalog._open_url = fake_open- with pytest.raises(PresetError, match="HTTPS"):- catalog.fetch_catalog(force_refresh=True)- assert captured["rv"] is not None-- @pytest.mark.parametrize(- "payload",- [- # Root is not a JSON object.- [],- "oops",- 42,- None,- # Root is fine but ``presets`` is the wrong type.- {"schema_version": "1.0", "presets": []},- {"schema_version": "1.0", "presets": "oops"},- {"schema_version": "1.0", "presets": None},- {"schema_version": "1.0", "presets": 42},- ],- )- def test_fetch_single_catalog_rejects_malformed_payload(self, project_dir, payload):- """Malformed catalog payloads raise PresetError, not AttributeError.-- Without this guard, a payload like ``{"presets": []}`` would pass the- key-presence check and then crash with ``AttributeError: 'list' object- has no attribute 'items'`` deep inside ``_get_merged_packs``. The- sibling integration catalog reader already validates both the root- object and the nested mapping (see ``integrations/catalog.py``); the- preset catalog must stay consistent.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)-- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- # A real urllib response reports the final URL (== request URL with no- # redirect); the fetcher re-validates it after redirects.- mock_response.geturl.return_value = "https://example.com/catalog.json"-- entry = PresetCatalogEntry(- url="https://example.com/catalog.json",- name="default",- priority=1,- install_allowed=True,- )-- with patch.object(catalog, "_open_url", return_value=mock_response):- with pytest.raises(PresetError, match="Invalid preset catalog format"):- catalog._fetch_single_catalog(entry, force_refresh=True)-- @pytest.mark.parametrize(- "cached_payload",- [- [],- "oops",- 42,- None,- {"schema_version": "1.0", "presets": []},- {"schema_version": "1.0", "presets": "oops"},- {"schema_version": "1.0", "presets": None},- ],- )- def test_fetch_single_catalog_rejects_malformed_cached_payload(- self, project_dir, cached_payload- ):- """A poisoned cache silently falls back to the network instead of- crashing β cached payloads pass through the same shape validation- as freshly-fetched ones.-- Without this, a cache poisoned by an older spec-kit version (or a- manual edit, or an upstream that briefly served a bad payload- before the network guards landed) would re-crash every invocation- of ``_get_merged_packs`` despite the cache being "valid" by age.- The recovery contract is: if the cached payload fails validation,- drop it and refetch β never propagate ``AttributeError`` to the- caller.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)-- # Poison the default-URL cache. ``DEFAULT_CATALOG_URL`` and- # non-default URLs both flow through the same cache-load branch.- cache_file, metadata_file = catalog._get_cache_paths(- catalog.DEFAULT_CATALOG_URL- )- cache_file.parent.mkdir(parents=True, exist_ok=True)- cache_file.write_text(json.dumps(cached_payload))- metadata_file.write_text(- json.dumps(- {- "cached_at": datetime.now(timezone.utc).isoformat(),- "catalog_url": catalog.DEFAULT_CATALOG_URL,- }- )- )-- # Network refetch returns a valid payload so the recovery path- # can complete.- valid = {- "schema_version": "1.0",- "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},- }- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = catalog.DEFAULT_CATALOG_URL-- entry = PresetCatalogEntry(- url=catalog.DEFAULT_CATALOG_URL,- name="default",- priority=1,- install_allowed=True,- )-- with patch.object(catalog, "_open_url", return_value=mock_response):- result = catalog._fetch_single_catalog(entry, force_refresh=False)-- # The poisoned cache was discarded and the network payload returned.- assert result == valid-- @pytest.mark.parametrize(- "payload",- [- # Root is not a JSON object.- [],- "oops",- 42,- None,- # Root is fine but ``presets`` is the wrong type.- {"schema_version": "1.0", "presets": []},- {"schema_version": "1.0", "presets": "oops"},- {"schema_version": "1.0", "presets": None},- ],- )- def test_fetch_catalog_rejects_malformed_payload(self, project_dir, payload):- """Legacy ``fetch_catalog`` reuses the same shape-validation helper.-- Before this change ``fetch_catalog`` only checked key presence β- so a payload like ``42`` would crash with- ``TypeError: argument of type 'int' is not iterable`` during the- ``"schema_version" in catalog_data`` check, and an entry mapping- of the wrong type would crash downstream. Reusing- ``_validate_catalog_payload`` keeps the network-side behaviour of- the legacy single-catalog method consistent with the multi-catalog- ``_fetch_single_catalog`` path.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://example.com/catalog.json"-- with patch.object(catalog, "_open_url", return_value=mock_response):- with pytest.raises(PresetError, match="Invalid preset catalog format"):- catalog.fetch_catalog(force_refresh=True)-- def test_fetch_catalog_recovers_from_unreadable_cache(self, project_dir):- """An unreadable / wrong-encoded cache file silently refetches.-- The cache contract is best-effort: a JSON-decode failure, an OS- read failure (permissions / disk / handle limit), or an invalid- text encoding on a cache file written by an older client must- all fall through to the network fetch rather than crash the- caller. Covers Copilot's review point that the previous- ``except (json.JSONDecodeError, OSError)`` was missing- ``UnicodeError``.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- # Invalid UTF-8 bytes so ``read_text`` raises ``UnicodeDecodeError``- # (a subclass of ``UnicodeError``).- catalog.cache_file.write_bytes(b"\xff\xfe\x00not-utf-8")- catalog.cache_metadata_file.write_text(- json.dumps(- {- "cached_at": datetime.now(timezone.utc).isoformat(),- "catalog_url": catalog.get_catalog_url(),- }- ),- encoding="utf-8",- )-- valid = {- "schema_version": "1.0",- "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},- }- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://example.com/catalog.json"-- with patch.object(catalog, "_open_url", return_value=mock_response):- result = catalog.fetch_catalog(force_refresh=False)-- # Recovered via network rather than crashing on the unreadable cache.- assert result == valid-- def test_fetch_catalog_recovers_from_unreadable_metadata(self, project_dir):- """A wrongly-encoded metadata file degrades to a cache miss.-- ``is_cache_valid`` is consulted *before* the cache payload is- read; if the metadata file itself can't be decoded (e.g. it was- written on a host whose default codec isn't UTF-8) the validity- check must return ``False`` rather than propagate- ``UnicodeDecodeError``. Without that guard, a corrupted metadata- file would crash every invocation instead of falling through to- a network refetch.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- catalog.cache_file.write_text("{}", encoding="utf-8")- # Bytes that are not valid UTF-8 β ``read_text(encoding="utf-8")``- # will raise ``UnicodeDecodeError`` (subclass of ``UnicodeError``).- catalog.cache_metadata_file.write_bytes(b"\xff\xfe\x00bad")-- # is_cache_valid must absorb the decode failure, not crash.- assert catalog.is_cache_valid() is False-- valid = {- "schema_version": "1.0",- "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},- }- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://example.com/catalog.json"-- with patch.object(catalog, "_open_url", return_value=mock_response):- result = catalog.fetch_catalog(force_refresh=False)-- assert result == valid-- @pytest.mark.parametrize(- "non_mapping_metadata",- [- "[]", # JSON array- '"oops"', # JSON string- "42", # JSON number- "true", # JSON bool- "null", # JSON null- ],- )- def test_is_cache_valid_handles_non_mapping_metadata(- self, project_dir, non_mapping_metadata- ):- """Metadata that parses to a non-mapping degrades to cache-invalid.-- The cache-validity check calls ``metadata.get("cached_at", "")``- immediately after ``json.loads``. If the metadata file is valid- JSON but parses to a non-mapping (``[]``, ``"oops"``, ``42``,- ``true``, ``null``), ``.get`` raises ``AttributeError`` β which- previously slipped past the except tuple and crashed the- caller. The contract documented on ``is_cache_valid`` says any- decode/shape failure should return ``False`` so ``fetch_catalog``- falls through to a network refetch. This test pins that- contract across every JSON non-mapping root type.- """- catalog = PresetCatalog(project_dir)- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- catalog.cache_file.write_text("{}", encoding="utf-8")- catalog.cache_metadata_file.write_text(- non_mapping_metadata, encoding="utf-8"- )-- # Must not raise β the contract is "any decode/shape failure β False".- assert catalog.is_cache_valid() is False-- def test_fetch_catalog_writes_cache_as_utf8(self, project_dir, monkeypatch):- """Cache + metadata writes pass ``encoding="utf-8"``, observably.-- The earlier version of this test claimed to assert UTF-8 at the- byte level but actually only round-tripped a non-ASCII string- through ``json.dumps`` and ``read_text(encoding="utf-8")``.- Because ``json.dumps`` defaults to ``ensure_ascii=True``, "cafΓ©"- was serialized as the all-ASCII escape ``caf\\u00e9`` before it- ever reached ``write_text`` β the bytes on disk were identical- regardless of the encoding kwarg. The drift Copilot's review- flagged wasn't actually being caught.-- Fix: directly observe the ``encoding`` argument passed to every- ``write_text`` call made against the cache directory. This is- the production code's encoding choice, which is exactly what- the regression guard cares about.- """- from unittest.mock import patch, MagicMock- from pathlib import Path as _PathCls-- catalog = PresetCatalog(project_dir)- payload = {- "schema_version": "1.0",- "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},- }- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode("utf-8")).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://example.com/catalog.json"-- # Record every ``write_text`` call's encoding kwarg so the- # assertion observes the production writer's argument directly.- recorded: list[dict] = []- real_write_text = _PathCls.write_text-- def recording_write_text(self, data, *args, **kwargs):- recorded.append(- {"path": str(self), "encoding": kwargs.get("encoding")}- )- return real_write_text(self, data, *args, **kwargs)-- monkeypatch.setattr(_PathCls, "write_text", recording_write_text)-- with patch.object(catalog, "_open_url", return_value=mock_response):- catalog.fetch_catalog(force_refresh=True)-- cache_writes = [- r for r in recorded if str(catalog.cache_dir) in r["path"]- ]- assert cache_writes, "fetch_catalog made no writes to the cache dir"- for record in cache_writes:- assert record["encoding"] == "utf-8", (- f"write_text on {record['path']} used encoding "- f"{record['encoding']!r}; expected 'utf-8'"- )-- def test_fetch_catalog_survives_unwritable_cache(self, project_dir, monkeypatch):- """An unwritable cache dir doesn't fail a successful fetch.-- Cache writes are best-effort, mirroring the read side and the- ``integrations/catalog.py`` precedent: if ``mkdir``/``write_text``- raises ``OSError`` (read-only checkout, permissions), the- already-fetched-and-validated payload must still be returned β- not swallowed into the broad except and re-raised as a- ``PresetError``.- """- from unittest.mock import patch, MagicMock- from pathlib import Path as _PathCls-- catalog = PresetCatalog(project_dir)- valid = {- "schema_version": "1.0",- "presets": {"foo": {"name": "Foo", "version": "1.0.0"}},- }- def make_response():- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(valid).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = catalog.DEFAULT_CATALOG_URL- return mock_response-- # Simulate an unwritable cache dir: every write_text under the- # cache directory raises PermissionError (an OSError subclass).- real_write_text = _PathCls.write_text-- def failing_write_text(self, data, *args, **kwargs):- if str(catalog.cache_dir) in str(self):- raise PermissionError("cache dir is read-only")- return real_write_text(self, data, *args, **kwargs)-- monkeypatch.setattr(_PathCls, "write_text", failing_write_text)-- with patch.object(catalog, "_open_url", side_effect=lambda *a, **kw: make_response()):- # Legacy single-catalog path.- assert catalog.fetch_catalog(force_refresh=True) == valid-- # Multi-catalog path.- entry = PresetCatalogEntry(- url=catalog.DEFAULT_CATALOG_URL,- name="default",- priority=1,- install_allowed=True,- )- assert (- catalog._fetch_single_catalog(entry, force_refresh=True) == valid- )-- def test_get_merged_packs_skips_non_mapping_entries(self, project_dir):- """Per-entry guard: one malformed entry shouldn't poison the merge.-- ``_fetch_single_catalog`` validates that ``presets`` is a mapping,- but it doesn't (and shouldn't) validate every entry inside it β a- single bad entry in an otherwise-valid catalog should be skipped,- not crash the whole resolve path. Mirrors the per-entry skip in- ``integrations/catalog.py``: a malformed entry returns no error,- valid entries continue to merge normally.- """- from unittest.mock import patch, MagicMock-- catalog = PresetCatalog(project_dir)- payload = {- "schema_version": "1.0",- "presets": {- "good": {"name": "Good", "version": "1.0.0"},- "bad-list": [],- "bad-str": "oops",- },- }- mock_response = MagicMock()- mock_response.read.side_effect = io.BytesIO(json.dumps(payload).encode()).read- mock_response.__enter__ = lambda s: s- mock_response.__exit__ = MagicMock(return_value=False)- mock_response.geturl.return_value = "https://example.com/catalog.json"-- entry = PresetCatalogEntry(- url="https://example.com/catalog.json",- name="default",- priority=1,- install_allowed=True,- )-- with patch.object(catalog, "_open_url", return_value=mock_response), \- patch.object(catalog, "get_active_catalogs", return_value=[entry]):- merged = catalog._get_merged_packs(force_refresh=True)-- # Only the well-formed entry survives; the two malformed entries are- # silently dropped rather than raising or crashing.- assert list(merged.keys()) == ["good"]-- def test_download_pack_sends_auth_header(self, project_dir, monkeypatch):- """download_pack passes Authorization header when configured."""- from unittest.mock import patch, MagicMock-- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)-- import io- zip_buf = io.BytesIO()- with zipfile.ZipFile(zip_buf, "w") as zf:- zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")- zip_bytes = zip_buf.getvalue()-- release_response = MagicMock()- release_response.read.side_effect = io.BytesIO(json.dumps(- {- "assets": [- {- "name": "test-pack.zip",- "url": "https://api.github.com/repos/org/repo/releases/assets/1",- }- ]- }- ).encode()).read- release_response.__enter__ = lambda s: s- release_response.__exit__ = MagicMock(return_value=False)-- asset_response = MagicMock()- asset_response.read.side_effect = io.BytesIO(zip_bytes).read- asset_response.__enter__ = lambda s: s- asset_response.__exit__ = MagicMock(return_value=False)-- captured = []- mock_opener = MagicMock()-- def fake_open(req, timeout=None):- captured.append(req)- if req.full_url.endswith("/releases/tags/v1"):- return release_response- return asset_response-- mock_opener.open.side_effect = fake_open-- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://github.com/org/repo/releases/download/v1/test-pack.zip",- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):- catalog.download_pack("test-pack", target_dir=project_dir)-- assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/tags/v1"- assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"- assert captured[1].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"- assert captured[1].get_header("Authorization") == "Bearer ghp_testtoken"- assert captured[1].get_header("Accept") == "application/octet-stream"-- def _pack_zip_and_response(self):- """Build a minimal preset ZIP and a context-manager mock response."""- from unittest.mock import MagicMock- import io-- zip_buf = io.BytesIO()- with zipfile.ZipFile(zip_buf, "w") as zf:- zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")- zip_bytes = zip_buf.getvalue()-- resp = MagicMock()- resp.read.side_effect = io.BytesIO(zip_bytes).read- # Configure the context-manager protocol explicitly so `with resp`- # yields `resp` itself, independent of how the protocol is invoked.- resp.__enter__.return_value = resp- resp.__exit__.return_value = False- return zip_bytes, resp-- def test_fetch_single_catalog_rejects_oversized_body_without_cache(- self, project_dir, monkeypatch- ):- """Catalog bounds are enforced at the preset call site."""- import specify_cli.presets as preset_module- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- entry = PresetCatalogEntry(- url="https://example.com/catalog.json",- name="default",- priority=1,- install_allowed=True,- )- body = b'{"schema_version":"1.0","presets":{}}'- response = MagicMock()- response.read.side_effect = io.BytesIO(body).read- response.__enter__.return_value = response- response.__exit__.return_value = False- response.geturl.return_value = entry.url- monkeypatch.setattr(- preset_module,- "MAX_JSON_CATALOG_BYTES",- len(body) - 1,- )-- with patch.object(catalog, "_open_url", return_value=response):- with pytest.raises(PresetError, match="exceeds maximum size"):- catalog._fetch_single_catalog(entry, force_refresh=True)-- assert not catalog.cache_dir.exists() or not any(catalog.cache_dir.iterdir())-- def test_download_pack_rejects_oversized_body_without_output(- self, project_dir, monkeypatch- ):- """Package bounds fail before checksum verification or disk writes."""- import specify_cli.presets as preset_module- from unittest.mock import patch- from specify_cli._download_security import (- read_response_limited as real_read_response_limited,- )-- catalog = PresetCatalog(project_dir)- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://example.com/test-pack.zip",- "_install_allowed": True,- }- response = MagicMock()- response.read.side_effect = io.BytesIO(b"12345").read- response.__enter__.return_value = response- response.__exit__.return_value = False-- def read_with_tiny_limit(stream, **kwargs):- kwargs.pop("max_bytes", None)- return real_read_response_limited(stream, max_bytes=4, **kwargs)-- monkeypatch.setattr(- preset_module,- "read_response_limited",- read_with_tiny_limit,- )- with patch.object(preset_module, "verify_archive_sha256") as verify, \- patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url", return_value=response):- with pytest.raises(PresetError, match="exceeds maximum size"):- catalog.download_pack("test-pack", target_dir=project_dir)-- verify.assert_not_called()- assert not (project_dir / "test-pack-1.0.0.zip").exists()-- def test_download_pack_rejects_unsafe_output_filename(self, project_dir):- """Catalog-controlled IDs cannot escape the requested target directory."""- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- outside_stem = project_dir.parent / "outside-preset"- pack_id = str(outside_stem)- pack_info = {- "id": pack_id,- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://example.com/test-pack.zip",- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url") as open_url:- with pytest.raises(PresetError, match="filename"):- catalog.download_pack(pack_id, target_dir=project_dir)-- open_url.assert_not_called()- assert not Path(f"{outside_stem}-1.0.0.zip").exists()-- def test_download_pack_accepts_matching_sha256(self, project_dir):- """A catalog ``sha256`` that matches the preset archive is accepted."""- import hashlib- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- zip_bytes, resp = self._pack_zip_and_response()- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://example.com/test-pack.zip",- "sha256": hashlib.sha256(zip_bytes).hexdigest(),- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url", return_value=resp):- zip_path = catalog.download_pack("test-pack", target_dir=project_dir)-- assert zip_path.read_bytes() == zip_bytes-- def test_download_pack_rejects_sha256_mismatch(self, project_dir):- """A catalog ``sha256`` that does not match the archive aborts install."""- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- _zip_bytes, resp = self._pack_zip_and_response()- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://example.com/test-pack.zip",- "sha256": "0" * 64, # deliberately wrong- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url", return_value=resp):- with pytest.raises(PresetError, match="[Ii]ntegrity"):- catalog.download_pack("test-pack", target_dir=project_dir)-- def test_download_pack_malformed_url_raises_preset_error(self, project_dir):- """A catalog ``download_url`` with a malformed authority (e.g. an- unterminated IPv6 bracket) surfaces a clean ``PresetError`` rather than- leaking a raw ``ValueError`` from ``urlparse``/``.hostname`` past the- command handler (which only catches ``PresetError``). Mirrors the- extensions coverage.- """- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- for bad_url in (- "https://[::1",- "https://[not-an-ip]/x",- "https://example.com:65536/x",- "https:///x",- 123,- ):- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": bad_url,- "_install_allowed": True,- }- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url") as open_url:- with pytest.raises(PresetError, match="malformed"):- catalog.download_pack("test-pack", target_dir=project_dir)- open_url.assert_not_called()-- def test_download_pack_without_sha256_skips_verification(self, project_dir):- """A catalog entry with no ``sha256`` keeps working: verification is- opt-in, so the backwards-compatible path (``pack_info.get("sha256")``- is ``None``) must download without aborting β mirrors the extensions- coverage so the helper never silently becomes mandatory for presets.- """- from unittest.mock import patch-- catalog = PresetCatalog(project_dir)- zip_bytes, resp = self._pack_zip_and_response()- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://example.com/test-pack.zip",- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url", return_value=resp):- zip_path = catalog.download_pack("test-pack", target_dir=project_dir)-- assert zip_path.read_bytes() == zip_bytes-- def test_download_pack_accepts_direct_github_rest_asset_url(self, project_dir, monkeypatch):- """download_pack can use a GitHub REST release asset URL directly."""- from unittest.mock import patch, MagicMock-- monkeypatch.setenv("GITHUB_TOKEN", "ghp_testtoken")- self._inject_github_config(monkeypatch, token_env="GITHUB_TOKEN")- catalog = PresetCatalog(project_dir)-- import io- zip_buf = io.BytesIO()- with zipfile.ZipFile(zip_buf, "w") as zf:- zf.writestr("preset.yml", "id: test-pack\nname: Test\nversion: 1.0.0\n")- zip_bytes = zip_buf.getvalue()-- asset_response = MagicMock()- asset_response.read.side_effect = io.BytesIO(zip_bytes).read- asset_response.__enter__ = lambda s: s- asset_response.__exit__ = MagicMock(return_value=False)-- captured = []- mock_opener = MagicMock()-- def fake_open(req, timeout=None):- captured.append(req)- return asset_response-- mock_opener.open.side_effect = fake_open-- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": "https://api.github.com/repos/org/repo/releases/assets/1",- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch("specify_cli.authentication.http.urllib.request.build_opener", return_value=mock_opener):- catalog.download_pack("test-pack", target_dir=project_dir)-- assert len(captured) == 1- assert captured[0].full_url == "https://api.github.com/repos/org/repo/releases/assets/1"- assert captured[0].get_header("Authorization") == "Bearer ghp_testtoken"- assert captured[0].get_header("Accept") == "application/octet-stream"-- @pytest.mark.parametrize("suffix", [".tar.gz", ".tgz"])- def test_download_pack_preserves_tar_archive_format(- self, project_dir, suffix- ):- from unittest.mock import patch, MagicMock-- archive_buffer = io.BytesIO()- with tarfile.open(fileobj=archive_buffer, mode="w:gz") as archive:- content = b"preset:\n id: test-pack\n"- member = tarfile.TarInfo("preset.yml")- member.size = len(content)- archive.addfile(member, io.BytesIO(content))- archive_bytes = archive_buffer.getvalue()- response = MagicMock()- response.read.side_effect = io.BytesIO(archive_bytes).read- response.__enter__.return_value = response- response.__exit__.return_value = False- catalog = PresetCatalog(project_dir)- pack_info = {- "id": "test-pack",- "name": "Test Pack",- "version": "1.0.0",- "download_url": f"https://example.com/test-pack{suffix}",- "_install_allowed": True,- }-- with patch.object(catalog, "get_pack_info", return_value=pack_info), \- patch.object(catalog, "_open_url", return_value=response):- archive_path = catalog.download_pack("test-pack", target_dir=project_dir)-- assert archive_path.name == "test-pack-1.0.0.tar.gz"- assert archive_path.read_bytes() == archive_bytes---# ===== Integration Tests =====---class TestIntegration:- """Integration tests for complete preset workflows."""-- def test_full_install_resolve_remove_cycle(self, project_dir, pack_dir):- """Test complete lifecycle: install β resolve β remove."""- # Install- manager = PresetManager(project_dir)- manifest = manager.install_from_directory(pack_dir, "0.1.5")- assert manifest.id == "test-pack"-- # Resolve β pack template should win over core- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "Custom Spec Template" in result.read_text()-- # Remove- manager.remove("test-pack")-- # Resolve β should fall back to core- result = resolver.resolve("spec-template")- assert result is not None- assert "Core Spec Template" in result.read_text()-- def test_override_beats_pack_beats_extension_beats_core(self, project_dir, pack_dir):- """Test the full priority stack: override > pack > extension > core."""- resolver = PresetResolver(project_dir)-- # Core should resolve- result = resolver.resolve_with_source("spec-template")- assert result["source"] == "core"-- # Add extension template- ext_dir = project_dir / ".specify" / "extensions" / "my-ext"- ext_templates_dir = ext_dir / "templates"- ext_templates_dir.mkdir(parents=True)- (ext_templates_dir / "spec-template.md").write_text("# Extension\n")-- # Register extension in registry- extensions_dir = project_dir / ".specify" / "extensions"- ext_registry = ExtensionRegistry(extensions_dir)- ext_registry.add("my-ext", {"version": "1.0.0", "priority": 10})-- result = resolver.resolve_with_source("spec-template")- assert result["source"] == "extension:my-ext v1.0.0"-- # Install pack β should win over extension- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- result = resolver.resolve_with_source("spec-template")- assert "test-pack" in result["source"]-- # Add override β should win over pack- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- (overrides_dir / "spec-template.md").write_text("# Override\n")-- result = resolver.resolve_with_source("spec-template")- assert result["source"] == "project override"-- def test_install_from_zip_then_resolve(self, project_dir, pack_dir, temp_dir):- """Test installing from ZIP and then resolving."""- # Create ZIP- zip_path = temp_dir / "test-pack.zip"- with zipfile.ZipFile(zip_path, 'w') as zf:- for file_path in pack_dir.rglob('*'):- if file_path.is_file():- arcname = file_path.relative_to(pack_dir)- zf.write(file_path, arcname)-- # Install- manager = PresetManager(project_dir)- manager.install_from_zip(zip_path, "0.1.5")-- # Resolve- resolver = PresetResolver(project_dir)- result = resolver.resolve("spec-template")- assert result is not None- assert "Custom Spec Template" in result.read_text()---# ===== PresetCatalogEntry Tests =====---class TestPresetCatalogEntry:- """Test PresetCatalogEntry dataclass."""-- def test_create_entry(self):- """Test creating a catalog entry."""- entry = PresetCatalogEntry(- url="https://example.com/catalog.json",- name="test",- priority=1,- install_allowed=True,- description="Test catalog",- )- assert entry.url == "https://example.com/catalog.json"- assert entry.name == "test"- assert entry.priority == 1- assert entry.install_allowed is True- assert entry.description == "Test catalog"-- def test_default_description(self):- """Test default empty description."""- entry = PresetCatalogEntry(- url="https://example.com/catalog.json",- name="test",- priority=1,- install_allowed=False,- )- assert entry.description == ""---# ===== Multi-Catalog Tests =====---class TestPresetCatalogMultiCatalog:- """Test multi-catalog support in PresetCatalog."""-- def test_default_active_catalogs(self, project_dir):- """Test that default catalogs are returned when no config exists."""- catalog = PresetCatalog(project_dir)- active = catalog.get_active_catalogs()- assert len(active) == 2- assert active[0].name == "default"- assert active[0].priority == 1- assert active[0].install_allowed is True- assert active[1].name == "community"- assert active[1].priority == 2- assert active[1].install_allowed is False------- def test_env_var_overrides_catalogs(self, project_dir, monkeypatch):- """Test that SPECKIT_PRESET_CATALOG_URL env var overrides defaults."""- monkeypatch.setenv(- "SPECKIT_PRESET_CATALOG_URL",- "https://custom.example.com/catalog.json",- )- catalog = PresetCatalog(project_dir)- active = catalog.get_active_catalogs()- assert len(active) == 1- assert active[0].name == "custom"- assert active[0].url == "https://custom.example.com/catalog.json"- assert active[0].install_allowed is True-- def test_project_config_overrides_defaults(self, project_dir):- """Test that project-level config overrides built-in defaults."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "my-catalog",- "url": "https://my.example.com/catalog.json",- "priority": 1,- "install_allowed": True,- }- ]- }))-- catalog = PresetCatalog(project_dir)- active = catalog.get_active_catalogs()- assert len(active) == 1- assert active[0].name == "my-catalog"- assert active[0].url == "https://my.example.com/catalog.json"-- def test_load_catalog_config_nonexistent(self, project_dir):- """Test loading config from nonexistent file returns None."""- catalog = PresetCatalog(project_dir)- result = catalog._load_catalog_config(- project_dir / ".specify" / "nonexistent.yml"- )- assert result is None-- def test_load_catalog_config_empty(self, project_dir):- """Test loading empty config returns None."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text("")-- catalog = PresetCatalog(project_dir)- result = catalog._load_catalog_config(config_path)- assert result is None-- def test_load_catalog_config_defaults_blank_names(self, project_dir):- """Blank and null names normalize by valid catalog order."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(- yaml.dump(- {- "catalogs": [- {"name": "skipped", "url": " "},- {- "name": None,- "url": "https://one.example.com/catalog.json",- },- {- "name": " ",- "url": "https://two.example.com/catalog.json",- },- {- "name": " padded-name ",- "url": "https://three.example.com/catalog.json",- },- ]- }- ),- encoding="utf-8",- )-- entries = PresetCatalog(project_dir)._load_catalog_config(config_path)-- assert [entry.name for entry in entries] == [- "catalog-1",- "catalog-2",- "padded-name",- ]-- @pytest.mark.parametrize("bad", [[], False, 0, ""])- def test_load_catalog_config_rejects_falsy_non_mapping_root(- self, project_dir, bad- ):- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.safe_dump(bad), encoding="utf-8")-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="expected a mapping"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_invalid_yaml(self, project_dir):- """Test loading invalid YAML raises error."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(": invalid: {{{")-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="Failed to read"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_not_a_list(self, project_dir):- """Test that non-list catalogs key raises error."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({"catalogs": "not-a-list"}))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="must be a list"):- catalog._load_catalog_config(config_path)-- @pytest.mark.parametrize("body", ["catalogs: {}\n", "catalogs: ''\n", "catalogs: 0\n", "catalogs: false\n"])- def test_load_catalog_config_rejects_falsy_non_list_catalogs(self, project_dir, body):- """A FALSY non-list ``catalogs:`` value must raise, like a truthy one- (``catalogs: "not-a-list"``) already does. The shape check sat behind- the emptiness check, so these were silently swallowed as "no catalogs"."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(body, encoding="utf-8")-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="must be a list"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_invalid_entry(self, project_dir):- """Test that non-dict entry raises error."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({"catalogs": ["not-a-dict"]}))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="expected a mapping"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_http_url_rejected(self, project_dir):- """Test that HTTP URLs are rejected."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "bad",- "url": "http://insecure.example.com/catalog.json",- "priority": 1,- }- ]- }))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="must use HTTPS"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_priority_sorting(self, project_dir):- """Test that catalogs are sorted by priority."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "low-priority",- "url": "https://low.example.com/catalog.json",- "priority": 10,- "install_allowed": False,- },- {- "name": "high-priority",- "url": "https://high.example.com/catalog.json",- "priority": 1,- "install_allowed": True,- },- ]- }))-- catalog = PresetCatalog(project_dir)- entries = catalog._load_catalog_config(config_path)- assert entries is not None- assert len(entries) == 2- assert entries[0].name == "high-priority"- assert entries[1].name == "low-priority"-- def test_load_catalog_config_invalid_priority(self, project_dir):- """Test that invalid priority raises error."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "bad",- "url": "https://example.com/catalog.json",- "priority": "not-a-number",- }- ]- }))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="Invalid priority"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_rejects_boolean_priority(self, project_dir):- """A YAML ``priority: true`` is a typo, not a request for priority 1.-- ``bool`` is a subclass of ``int`` in Python, so ``int(True)`` silently- returns ``1``. Without an explicit guard a malformed config like- ``priority: yes`` would be accepted as a valid priority of 1 and- silently change catalog ordering. The sibling integration-catalog- reader rejects this case (see ``catalogs.py``); the preset catalog- reader must stay consistent.- """- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "bool-priority",- "url": "https://example.com/catalog.json",- "priority": True,- }- ]- }))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="Invalid priority|expected integer"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_rejects_infinite_priority(self, project_dir):- """A ``priority: .inf`` yields a clean validation error, not an uncaught- OverflowError from int(float('inf'))."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "inf-priority",- "url": "https://example.com/catalog.json",- "priority": float("inf"),- }- ]- }))-- catalog = PresetCatalog(project_dir)- with pytest.raises(PresetValidationError, match="Invalid priority|expected integer"):- catalog._load_catalog_config(config_path)-- def test_load_catalog_config_install_allowed_string(self, project_dir):- """Test that install_allowed accepts string values."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "test",- "url": "https://example.com/catalog.json",- "priority": 1,- "install_allowed": "true",- }- ]- }))-- catalog = PresetCatalog(project_dir)- entries = catalog._load_catalog_config(config_path)- assert entries is not None- assert entries[0].install_allowed is True-- def test_get_catalog_url_uses_highest_priority(self, project_dir):- """Test that get_catalog_url returns URL of highest priority catalog."""- config_path = project_dir / ".specify" / "preset-catalogs.yml"- config_path.write_text(yaml.dump({- "catalogs": [- {- "name": "secondary",- "url": "https://secondary.example.com/catalog.json",- "priority": 5,- },- {- "name": "primary",- "url": "https://primary.example.com/catalog.json",- "priority": 1,- },- ]- }))-- catalog = PresetCatalog(project_dir)- assert catalog.get_catalog_url() == "https://primary.example.com/catalog.json"-- def test_cache_paths_default_url(self, project_dir):- """Test cache paths for default catalog URL use legacy locations."""- catalog = PresetCatalog(project_dir)- cache_file, metadata_file = catalog._get_cache_paths(- PresetCatalog.DEFAULT_CATALOG_URL- )- assert cache_file == catalog.cache_file- assert metadata_file == catalog.cache_metadata_file-- def test_cache_paths_custom_url(self, project_dir):- """Test cache paths for custom URLs use hash-based files."""- catalog = PresetCatalog(project_dir)- cache_file, metadata_file = catalog._get_cache_paths(- "https://custom.example.com/catalog.json"- )- assert cache_file != catalog.cache_file- assert "catalog-" in cache_file.name- assert cache_file.name.endswith(".json")-- def test_url_cache_valid(self, project_dir):- """Test URL-specific cache validation."""- catalog = PresetCatalog(project_dir)- url = "https://custom.example.com/catalog.json"- cache_file, metadata_file = catalog._get_cache_paths(url)-- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))- metadata_file.write_text(json.dumps({- "cached_at": datetime.now(timezone.utc).isoformat(),- }))-- assert catalog._is_url_cache_valid(url) is True-- def test_url_cache_expired(self, project_dir):- """Test URL-specific cache expiration."""- catalog = PresetCatalog(project_dir)- url = "https://custom.example.com/catalog.json"- cache_file, metadata_file = catalog._get_cache_paths(url)-- catalog.cache_dir.mkdir(parents=True, exist_ok=True)- cache_file.write_text(json.dumps({"schema_version": "1.0", "presets": {}}))- metadata_file.write_text(json.dumps({- "cached_at": "2020-01-01T00:00:00+00:00",- }))-- assert catalog._is_url_cache_valid(url) is False---# ===== Self-Test Preset Tests =====---class TestSelfTestPreset:- """Tests using the self-test preset that ships with the repo.-- The self-test preset ships a wrap-strategy command (``speckit.wrap-test``)- without a corresponding core base layer; reconciliation deliberately- surfaces a UserWarning in that case. Tests install via- ``install_self_test_preset`` (defined above), which scopes a narrow- ``warnings.filterwarnings`` block to that specific message and- ``UserWarning`` category β so the expected warning stays quiet without- masking unrelated warnings or real reconciliation failures.- """-- def test_self_test_preset_exists(self):- """Verify the self-test preset directory and manifest exist."""- assert SELF_TEST_PRESET_DIR.exists()- assert (SELF_TEST_PRESET_DIR / "preset.yml").exists()-- def test_self_test_manifest_valid(self):- """Verify the self-test preset manifest is valid."""- manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")- assert manifest.id == "self-test"- assert manifest.name == "Self-Test Preset"- assert manifest.version == "1.0.0"- assert len(manifest.templates) == 7 # 5 templates + 2 commands-- def test_self_test_provides_all_core_templates(self):- """Verify the self-test preset provides an override for every core template."""- manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")- provided_names = {t["name"] for t in manifest.templates}- for name in CORE_TEMPLATE_NAMES:- assert name in provided_names, f"Self-test preset missing template: {name}"-- def test_self_test_template_files_exist(self):- """Verify that all declared template files actually exist on disk."""- manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")- for tmpl in manifest.templates:- tmpl_path = SELF_TEST_PRESET_DIR / tmpl["file"]- assert tmpl_path.exists(), f"Missing template file: {tmpl['file']}"-- def test_self_test_templates_have_marker(self):- """Verify each template contains the preset:self-test marker."""- for name in CORE_TEMPLATE_NAMES:- tmpl_path = SELF_TEST_PRESET_DIR / "templates" / f"{name}.md"- content = tmpl_path.read_text()- assert "preset:self-test" in content, f"{name}.md missing preset:self-test marker"-- def test_install_self_test_preset(self, project_dir):- """Test installing the self-test preset from its directory."""- manager = PresetManager(project_dir)- manifest = install_self_test_preset(manager)- assert manifest.id == "self-test"- assert manager.registry.is_installed("self-test")-- def test_self_test_overrides_all_core_templates(self, project_dir):- """Test that installing self-test overrides every core template."""- # Set up core templates in the project- templates_dir = project_dir / ".specify" / "templates"- for name in CORE_TEMPLATE_NAMES:- (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")-- # Install self-test preset- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- # Every core template should now resolve from the preset- resolver = PresetResolver(project_dir)- for name in CORE_TEMPLATE_NAMES:- result = resolver.resolve(name)- assert result is not None, f"{name} did not resolve"- content = result.read_text()- assert "preset:self-test" in content, (- f"{name} resolved but not from self-test preset"- )-- def test_self_test_resolve_with_source(self, project_dir):- """Test that resolve_with_source attributes templates to self-test."""- templates_dir = project_dir / ".specify" / "templates"- for name in CORE_TEMPLATE_NAMES:- (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- resolver = PresetResolver(project_dir)- for name in CORE_TEMPLATE_NAMES:- result = resolver.resolve_with_source(name)- assert result is not None, f"{name} did not resolve"- assert "self-test" in result["source"], (- f"{name} source is '{result['source']}', expected self-test"- )-- def test_self_test_removal_restores_core(self, project_dir):- """Test that removing self-test falls back to core templates."""- templates_dir = project_dir / ".specify" / "templates"- for name in CORE_TEMPLATE_NAMES:- (templates_dir / f"{name}.md").write_text(f"# Core {name}\n")-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)- manager.remove("self-test")-- resolver = PresetResolver(project_dir)- for name in CORE_TEMPLATE_NAMES:- result = resolver.resolve_with_source(name)- assert result is not None- assert result["source"] == "core"-- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert memory.read_text() == "# Core constitution-template\n"-- def test_self_test_removal_preserves_edited_constitution(self, project_dir):- """Removing a preset does not overwrite an edited generated constitution."""- templates_dir = project_dir / ".specify" / "templates"- (templates_dir / "constitution-template.md").write_text("# Core Constitution\n")-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)- memory = project_dir / ".specify" / "memory" / "constitution.md"- edited = memory.read_text() + "\n## Authored amendment\n"- memory.write_text(edited)-- manager.remove("self-test")-- assert memory.read_text() == edited-- def test_self_test_not_in_catalog(self):- """Verify the self-test preset is NOT in the catalog (it's local-only)."""- catalog_path = Path(__file__).parent.parent / "presets" / "catalog.json"- catalog_data = json.loads(catalog_path.read_text())- assert "self-test" not in catalog_data["presets"]-- def test_self_test_has_command(self):- """Verify the self-test preset includes a command override."""- manifest = PresetManifest(SELF_TEST_PRESET_DIR / "preset.yml")- commands = [t for t in manifest.templates if t["type"] == "command"]- assert len(commands) >= 1- assert commands[0]["name"] == "speckit.specify"-- def test_self_test_command_file_exists(self):- """Verify the self-test command file exists on disk."""- cmd_path = SELF_TEST_PRESET_DIR / "commands" / "speckit.specify.md"- assert cmd_path.exists()- content = cmd_path.read_text()- assert "preset:self-test" in content-- def test_self_test_registers_commands_for_claude(self, project_dir):- """Test that installing self-test registers skills in .claude/skills/."""- # Create Claude skills directory to simulate Claude being set up- claude_dir = project_dir / ".claude" / "skills"- claude_dir.mkdir(parents=True)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- # Check the skill was registered- cmd_file = claude_dir / "speckit-specify" / "SKILL.md"- assert cmd_file.exists(), "Skill not registered in .claude/skills/"- content = cmd_file.read_text()- assert "self-test" in content- assert "source:" in content # skill frontmatter includes metadata.source-- def test_self_test_registers_commands_for_gemini(self, project_dir):- """Test that installing self-test registers commands in .gemini/commands/ as TOML."""- # Create Gemini agent directory- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- # Check the command was registered in TOML format- cmd_file = gemini_dir / "speckit.specify.toml"- assert cmd_file.exists(), "Command not registered in .gemini/commands/"- content = cmd_file.read_text()- assert "prompt" in content # TOML format has a prompt field- assert "{{args}}" in content # Gemini uses {{args}} placeholder-- def test_self_test_unregisters_commands_on_remove(self, project_dir):- """Test that removing self-test cleans up registered commands."""- claude_dir = project_dir / ".claude" / "skills"- claude_dir.mkdir(parents=True)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- cmd_file = claude_dir / "speckit-specify" / "SKILL.md"- assert cmd_file.exists()-- manager.remove("self-test")- assert not cmd_file.exists(), "Command not cleaned up after preset removal"-- def test_self_test_no_commands_without_agent_dirs(self, project_dir):- """Test that no commands are registered when no agent dirs exist."""- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- metadata = manager.registry.get("self-test")- assert metadata["registered_commands"] == {}-- def test_self_test_does_not_seed_constitution_without_sync(self, project_dir):- """Installing a preset does not materialize its constitution by default."""- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert not memory.exists()-- def test_self_test_preserves_generated_constitution_without_sync(self, project_dir):- """Preset install and removal preserve generated content without the opt-in."""- resolver = PresetResolver(project_dir)- bundled_core = resolver._find_bundled_core(- "constitution-template", "template", ".md"- )- assert bundled_core is not None- core = bundled_core.read_bytes()- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- memory.write_bytes(core)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)- manager.remove("self-test")-- assert memory.read_bytes() == core-- def test_self_test_seeds_constitution_with_sync(self, project_dir):- """constitution-sync preserves the previous install-time seeding behavior."""- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert "preset:self-test" in memory.read_text()- assert "[PROJECT_NAME]" not in memory.read_text()-- @pytest.mark.parametrize(- "provenance_content",- [- '{"sha256": "does-not-match", "source": "old-preset"}\n',- "{not valid json",- ],- ids=["hash-mismatch", "malformed"],- )- def test_self_test_preserves_core_content_with_existing_invalid_provenance(- self, project_dir, provenance_content- ):- """A present invalid sidecar disables legacy core-template migration."""- resolver = PresetResolver(project_dir)- bundled_core = resolver._find_bundled_core(- "constitution-template", "template", ".md"- )- assert bundled_core is not None- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- memory.write_bytes(bundled_core.read_bytes())- (memory.parent / ".constitution-template.json").write_text(- provenance_content- )- original = memory.read_bytes()-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- assert memory.read_bytes() == original-- def test_self_test_preserves_mutable_project_core_copy(self, project_dir):- """A project template copy does not establish generated provenance."""- authored = "# Acme Organization Constitution\n\nOrganization policy.\n"- project_template = (- project_dir / ".specify" / "templates" / "constitution-template.md"- )- project_template.write_text(authored)- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- memory.write_text(authored)-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- assert memory.read_text() == authored- assert not (memory.parent / ".constitution-template.json").exists()-- def test_core_prefixed_preset_does_not_establish_generated_provenance(- self, project_dir, temp_dir- ):- """A preset ID beginning with core is not an immutable core source."""- authored = "# Acme Organization Constitution\n\nOrganization policy.\n"- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- memory.write_text(authored)-- preset_dir = temp_dir / "core-company"- (preset_dir / "templates").mkdir(parents=True)- (preset_dir / "templates" / "constitution-template.md").write_text(authored)- (preset_dir / "preset.yml").write_text(- yaml.safe_dump(- {- "schema_version": "1.0",- "preset": {- "id": "core-company",- "name": "Core Company",- "version": "1.0.0",- "description": "Company constitution preset",- "author": "Test Author",- "repository": "https://github.com/test/core-company",- "license": "MIT",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "constitution-template",- "file": "templates/constitution-template.md",- "description": "Company constitution",- "replaces": "constitution-template",- }- ]- },- }- )- )-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- manager.install_from_directory(preset_dir, "0.1.5")-- assert memory.read_text() == authored- assert not (memory.parent / ".constitution-template.json").exists()-- def test_self_test_preserves_authored_constitution_with_placeholder(- self, project_dir- ):- """A placeholder mention does not establish generated provenance."""- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- authored = "# Acme Constitution\n\nGuidance for [PROJECT_NAME].\n"- memory.write_text(authored)-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- assert memory.read_text() == authored-- def test_self_test_preserves_authored_constitution(self, project_dir):- """An authored (placeholder-free) constitution is never overwritten."""- memory = project_dir / ".specify" / "memory" / "constitution.md"- memory.parent.mkdir(parents=True, exist_ok=True)- authored = "# Acme Constitution\n\n### I. Ship It\nAuthored by a human.\n"- memory.write_text(authored)-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- assert memory.read_text() == authored, "authored constitution was overwritten"-- def test_self_test_override_resolves_constitution_template(self, project_dir):- """The preset override of constitution-template resolves to the preset file."""- templates_dir = project_dir / ".specify" / "templates"- (templates_dir / "constitution-template.md").write_text("# Core constitution\n")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- resolver = PresetResolver(project_dir)- result = resolver.resolve("constitution-template", "template")- assert result is not None- assert "preset:self-test" in result.read_text()-- def test_constitution_seed_composes_wrap_strategy(self, project_dir, temp_dir):- """Seeding memory composes wrap constitution-template layers."""- templates_dir = project_dir / ".specify" / "templates"- templates_dir.mkdir(parents=True, exist_ok=True)- (templates_dir / "constitution-template.md").write_text(- "# Core Constitution\n\n## Core Principle\n"- )-- preset_dir = temp_dir / "constitution-wrap"- (preset_dir / "templates").mkdir(parents=True)- (preset_dir / "templates" / "constitution-template.md").write_text(- "# Wrapper Constitution\n\n{CORE_TEMPLATE}\n\n## Wrapper Footer\n"- )- (preset_dir / "preset.yml").write_text(- yaml.dump(- {- "schema_version": "1.0",- "preset": {- "id": "constitution-wrap",- "name": "Constitution Wrap",- "version": "1.0.0",- "description": "Wrap constitution template for testing",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "constitution-template",- "file": "templates/constitution-template.md",- "strategy": "wrap",- "description": "Wrapped constitution template",- }- ]- },- }- )- )-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- manager.install_from_directory(preset_dir, "0.1.5")-- memory = project_dir / ".specify" / "memory" / "constitution.md"- content = memory.read_text()- assert "{CORE_TEMPLATE}" not in content- assert "# Wrapper Constitution" in content- assert "## Core Principle" in content-- def test_constitution_follows_priority_when_winning_preset_removed(- self, project_dir, temp_dir- ):- """An unchanged generated constitution follows priority and fallback layers."""- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- preset_dir = temp_dir / "higher-priority"- (preset_dir / "templates").mkdir(parents=True)- (preset_dir / "templates" / "constitution-template.md").write_text(- "# Higher Priority Constitution\n"- )- (preset_dir / "preset.yml").write_text(- yaml.dump(- {- "schema_version": "1.0",- "preset": {- "id": "higher-priority",- "name": "Higher Priority",- "version": "1.0.0",- "description": "Higher-priority constitution",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "constitution-template",- "file": "templates/constitution-template.md",- "strategy": "replace",- "description": "Higher-priority constitution",- }- ]- },- }- )- )-- manager.install_from_directory(preset_dir, "0.1.5", priority=1)-- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert memory.read_text() == "# Higher Priority Constitution\n"-- manager.remove("higher-priority")-- assert "preset:self-test" in memory.read_text()-- def test_convention_constitution_removal_restores_remaining_layer(- self, project_dir, temp_dir- ):- """Removing a convention layer rematerializes the remaining resolver layer."""- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)- manager.install_from_directory(- _make_convention_constitution_preset(temp_dir), "0.1.5", priority=1- )-- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert memory.read_text() == "# Convention Constitution\n"-- manager.remove("convention-constitution")-- assert "preset:self-test" in memory.read_text()-- def test_convention_constitution_removal_preserves_edited_content(- self, project_dir, temp_dir- ):- """Removing a convention layer does not overwrite edited generated content."""- from specify_cli.command_init import ensure_constitution_from_template-- templates_dir = project_dir / ".specify" / "templates"- (templates_dir / "constitution-template.md").write_text("# Core Constitution\n")- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- manager.install_from_directory(- _make_convention_constitution_preset(temp_dir), "0.1.5"- )- ensure_constitution_from_template(project_dir)- memory = project_dir / ".specify" / "memory" / "constitution.md"- edited = memory.read_text() + "\n## Authored amendment\n"- memory.write_text(edited)-- manager.remove("convention-constitution")-- assert memory.read_text() == edited-- def test_custom_constitution_removal_recovers_with_invalid_manifest(- self, project_dir, temp_dir- ):- """Provenance triggers fallback when a custom-path manifest is invalid."""- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- install_self_test_preset(manager)-- preset_dir = temp_dir / "custom-constitution"- (preset_dir / "policy").mkdir(parents=True)- (preset_dir / "policy" / "charter.md").write_text("# Custom Constitution\n")- (preset_dir / "preset.yml").write_text(- yaml.dump(- {- "schema_version": "1.0",- "preset": {- "id": "custom-constitution",- "name": "Custom Constitution",- "version": "1.0.0",- "description": "Custom-path constitution for testing",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "constitution-template",- "file": "policy/charter.md",- }- ]- },- }- )- )- manager.install_from_directory(preset_dir, "0.1.5", priority=1)- memory = project_dir / ".specify" / "memory" / "constitution.md"- assert memory.read_text() == "# Custom Constitution\n"-- installed_manifest = (- project_dir- / ".specify"- / "presets"- / "custom-constitution"- / "preset.yml"- )- installed_manifest.write_text("invalid: [")-- manager.remove("custom-constitution")-- assert "preset:self-test" in memory.read_text()-- def test_constitution_seed_rejects_symlinked_memory_directory(- self, project_dir, temp_dir- ):- """Preset installation cannot seed through a symlinked memory directory."""- outside = temp_dir / "outside"- outside.mkdir()- try:- (project_dir / ".specify" / "memory").symlink_to(- outside, target_is_directory=True- )- except OSError:- pytest.skip("symlinks are unavailable")-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="symlinked"):- install_constitution_sync_preset(manager)-- assert manager.registry.is_installed("constitution-sync")- assert not (outside / "constitution.md").exists()-- def test_constitution_seed_rejects_dangling_destination_symlink(- self, project_dir, temp_dir- ):- """Preset installation cannot seed through a dangling destination symlink."""- memory = project_dir / ".specify" / "memory"- memory.mkdir(parents=True)- outside = temp_dir / "outside-constitution.md"- try:- (memory / "constitution.md").symlink_to(outside)- except OSError:- pytest.skip("symlinks are unavailable")-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="symlinked"):- install_constitution_sync_preset(manager)-- assert manager.registry.is_installed("constitution-sync")- assert not outside.exists()-- def test_constitution_materialization_error_is_nonfatal(- self, project_dir, temp_dir- ):- """An invalid wrap warns without reporting an uninstalled preset."""- preset_dir = temp_dir / "invalid-wrap"- (preset_dir / "templates").mkdir(parents=True)- (preset_dir / "templates" / "constitution-template.md").write_text(- "# Missing core placeholder\n"- )- (preset_dir / "preset.yml").write_text(- yaml.dump(- {- "schema_version": "1.0",- "preset": {- "id": "invalid-wrap",- "name": "Invalid Wrap",- "version": "1.0.0",- "description": "Invalid wrapping constitution",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "template",- "name": "constitution-template",- "file": "templates/constitution-template.md",- "strategy": "wrap",- "description": "Invalid wrap",- }- ]- },- }- )- )-- manager = PresetManager(project_dir)- install_constitution_sync_preset(manager)- with pytest.warns(UserWarning, match="Failed to seed constitution"):- manifest = manager.install_from_directory(preset_dir, "0.1.5")-- assert manifest.id == "invalid-wrap"- assert manager.registry.is_installed("invalid-wrap")-- def test_selfcontained_namespaced_command_scaffolds_without_extension(self, project_dir, temp_dir):- """A preset shipping a self-contained ``speckit.<ns>.<cmd>`` command- scaffolds even when no matching extension is installed.-- The command template ships its own body, so it is self-contained and- must render just like a short ``speckit.<cmd>`` command. It is not- dropped merely because ``.specify/extensions/fakeext/`` is absent.- """- claude_dir = project_dir / ".claude" / "skills"- claude_dir.mkdir(parents=True)-- preset_dir = temp_dir / "ext-override-preset"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\nOverridden content"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "ext-override",- "name": "Ext Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- "description": "Override fakeext cmd",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Extension not installed, but the preset ships its own command body β- # it must scaffold (as a native-skill SKILL.md for claude) and be- # tracked in the preset's registered_commands.- skill_file = claude_dir / "speckit-fakeext-cmd" / "SKILL.md"- assert skill_file.exists(), "Self-contained namespaced command was dropped"- metadata = manager.registry.get("ext-override")- assert metadata["registered_commands"] != {}-- def test_extension_command_registered_when_extension_present(self, project_dir, temp_dir):- """Test that extension command overrides ARE registered when the extension is installed."""- claude_dir = project_dir / ".claude" / "skills"- claude_dir.mkdir(parents=True)- (project_dir / ".specify" / "extensions" / "fakeext").mkdir(parents=True)-- preset_dir = temp_dir / "ext-override-preset2"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\nOverridden content"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "ext-override2",- "name": "Ext Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- "description": "Override fakeext cmd",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_file = claude_dir / "speckit-fakeext-cmd" / "SKILL.md"- assert cmd_file.exists(), "Skill not registered despite extension being present"---# ===== Init Options and Skills Tests =====---class TestInitOptions:- """Tests for save_init_options / load_init_options helpers."""-- def test_save_and_load_round_trip(self, project_dir):- from specify_cli import save_init_options, load_init_options-- opts = {"ai": "claude", "ai_skills": True, "here": False}- save_init_options(project_dir, opts)-- loaded = load_init_options(project_dir)- assert loaded["ai"] == "claude"- assert loaded["ai_skills"] is True-- def test_save_and_load_available_from_init_options_module(self, project_dir):- from specify_cli._init_options import load_init_options, save_init_options-- opts = {"ai": "codex", "ai_skills": True, "script": "sh"}- save_init_options(project_dir, opts)-- assert load_init_options(project_dir) == opts-- def test_save_uses_utf8_encoding(self, project_dir, monkeypatch):- from specify_cli import save_init_options-- original_write_text = Path.write_text- seen: dict[str, str | None] = {}-- def spy_write_text(path, data, *args, **kwargs):- if path == project_dir / ".specify" / "init-options.json":- seen["encoding"] = kwargs.get("encoding")- return original_write_text(path, data, *args, **kwargs)-- monkeypatch.setattr(Path, "write_text", spy_write_text)-- save_init_options(project_dir, {"label": "δΈζζ΅θ―"})-- assert seen["encoding"] == "utf-8"-- def test_load_uses_utf8_encoding(self, project_dir, monkeypatch):- from specify_cli import load_init_options-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.write_text('{"ai": "codex"}', encoding="utf-8")-- original_read_text = Path.read_text- seen: dict[str, str | None] = {}-- def spy_read_text(path, *args, **kwargs):- if path == opts_file:- seen["encoding"] = kwargs.get("encoding")- return original_read_text(path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", spy_read_text)-- assert load_init_options(project_dir) == {"ai": "codex"}- assert seen["encoding"] == "utf-8"-- def test_load_returns_empty_when_missing(self, project_dir):- from specify_cli import load_init_options-- assert load_init_options(project_dir) == {}-- def test_load_returns_empty_on_invalid_json(self, project_dir):- from specify_cli import load_init_options-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.write_text("{bad json")-- assert load_init_options(project_dir) == {}-- @pytest.mark.parametrize(- "value",- ["εε-γγγΈγ§γ―γ", "cafΓ©-rΓ©sumΓ©", "Ξ©mega-Ξelta", "π-launch"],- )- def test_save_load_round_trip_preserves_non_ascii(self, project_dir, value):- """Non-ASCII values round-trip via explicit UTF-8 encoding.-- ``Path.write_text`` / ``Path.read_text`` default to the system- locale codec on Windows (cp1252 / gb2312 / cp932). Without- ``encoding="utf-8"`` pinned on both ends, a project name like- ``cafΓ©`` written on a UTF-8 host becomes garbled or unreadable on- a cp1252 host (and vice versa). Pin UTF-8 explicitly so init- options round-trip across machines and CI.-- Note: this test only meaningfully exercises the encoding pin- because ``save_init_options`` now writes JSON with- ``ensure_ascii=False`` β otherwise ``json.dumps`` would output- ASCII-only ``\\uXXXX`` escapes and the encoding pin would be a- no-op for any value here. ``test_save_writes_real_utf8_bytes``- below asserts that contract directly.- """- from specify_cli import save_init_options, load_init_options-- save_init_options(project_dir, {"ai": "claude", "project_name": value})-- loaded = load_init_options(project_dir)- assert loaded["project_name"] == value-- def test_save_writes_real_utf8_bytes(self, project_dir):- """The on-disk file contains real UTF-8 bytes, not ``\\uXXXX`` escapes.-- Pinning ``encoding="utf-8"`` on ``write_text`` only makes a- difference when the serialiser actually emits non-ASCII- characters. With ``ensure_ascii=False`` on ``json.dumps`` the- non-ASCII bytes hit the file, so the encoding pin is the thing- that decides between cp1252 garbage and clean UTF-8 on Windows.-- This test pins that behaviour: the on-disk bytes are valid UTF-8- and contain the multi-byte encoding of ``cafΓ©``, not its- ``\\u00e9`` escape form. Reviewers can verify that removing- ``ensure_ascii=False`` or ``encoding="utf-8"`` from the writer- breaks this test, which is what Copilot's review pointed out the- original round-trip test failed to do.- """- from specify_cli import save_init_options-- save_init_options(project_dir, {"project_name": "cafΓ©"})-- opts_file = project_dir / ".specify" / "init-options.json"- raw = opts_file.read_bytes()- # 'cafΓ©' in UTF-8 ends with bytes 0xC3 0xA9 ('Γ©'). The cp1252- # encoding of 'Γ©' is the single byte 0xE9. The JSON-escape form- # would be the 6-byte literal '\\u00e9'. We assert the UTF-8 form- # is present so the test pins the actual contract.- assert b"caf\xc3\xa9" in raw, (- "Expected UTF-8 bytes for 'cafΓ©' in the on-disk file, "- f"got: {raw!r}"- )- # And the whole file decodes cleanly as UTF-8.- raw.decode("utf-8")-- def test_load_returns_empty_on_locale_corrupted_file(self, project_dir):- """A file written in a non-UTF-8 codec falls back to {}, not crash.-- Simulates a file produced by an old client (or by a peer machine- with a different default locale) that contains bytes invalid as- UTF-8. ``load_init_options`` should fall back to ``{}`` per the- existing contract β never propagate a raw ``UnicodeDecodeError``- to the CLI surface.- """- from specify_cli import load_init_options-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- # 0xE9 is 'Γ©' in cp1252 but an invalid lead byte in UTF-8.- opts_file.write_bytes(b'{"project_name": "caf\xe9"}')-- assert load_init_options(project_dir) == {}-- @pytest.mark.parametrize("payload", ["[]", '"value"', "42", "true", "null"])- def test_load_returns_empty_on_non_object_json(self, project_dir, payload):- from specify_cli import load_init_options-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.write_text(payload, encoding="utf-8")-- assert load_init_options(project_dir) == {}-- def test_load_returns_empty_on_unicode_decode_error(self, project_dir, monkeypatch):- from specify_cli import load_init_options-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.write_bytes(b"{}")-- original_read_text = Path.read_text-- def raise_decode_error(path, *args, **kwargs):- if path == opts_file:- raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte")- return original_read_text(path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", raise_decode_error)-- assert load_init_options(project_dir) == {}-- @pytest.mark.parametrize(- ("value", "expected"),- [- (True, True),- (False, False),- ("true", False),- ("false", False),- (1, False),- (0, False),- (None, False),- ],- )- def test_is_ai_skills_enabled_requires_boolean_true(self, value, expected):- from specify_cli._init_options import is_ai_skills_enabled-- assert is_ai_skills_enabled({"ai_skills": value}) is expected---class TestResolveActiveAgentForRegistration:- """Tests for the shared #2948 active-agent resolution helper.-- ``load_init_options`` collapses "no file", "corrupted file", and- "valid file with no active agent" into the same ``{}``. Extensions and- presets both need to tell those apart: no file means "legacy project,- fall back to all detected agents"; a corrupted or malformed file means- "fail closed, register nothing" so a corrupted init-options.json can't- silently reintroduce all-agent registration.- """-- def test_missing_file_returns_sentinel(self, project_dir):- from specify_cli._init_options import (- MISSING_INIT_OPTIONS_FILE,- resolve_active_agent_for_registration,- )-- assert (- resolve_active_agent_for_registration(project_dir)- is MISSING_INIT_OPTIONS_FILE- )-- def test_valid_active_agent_returns_string(self, project_dir):- from specify_cli import save_init_options- from specify_cli._init_options import resolve_active_agent_for_registration-- save_init_options(project_dir, {"ai": "claude"})-- assert resolve_active_agent_for_registration(project_dir) == "claude"-- def test_corrupted_json_fails_closed(self, project_dir):- """A present-but-unparseable file must not behave like "no file"."""- from specify_cli._init_options import resolve_active_agent_for_registration-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.write_text("{bad json", encoding="utf-8")-- assert resolve_active_agent_for_registration(project_dir) is None-- @pytest.mark.parametrize("value", [[], {}, "", 0, None, ["claude"]])- def test_malformed_ai_value_fails_closed(self, project_dir, value):- """A recorded but non-string/empty ``ai`` value fails closed too."""- from specify_cli import save_init_options- from specify_cli._init_options import resolve_active_agent_for_registration-- save_init_options(project_dir, {"ai": value})-- assert resolve_active_agent_for_registration(project_dir) is None-- def test_dangling_symlink_fails_closed(self, project_dir):- """A dangling init-options.json symlink must fail closed, not fall- back to "no file" (#2948).-- ``Path.exists()`` follows symlinks and returns False for a broken- symlink whose target is missing, so a naive presence check treats a- dangling symlink the same as "no file at all" and falls back to- legacy all-agent registration. The path is present (just broken),- so it must be treated as a corrupted file and fail closed instead.- """- from specify_cli._init_options import resolve_active_agent_for_registration-- opts_file = project_dir / ".specify" / "init-options.json"- opts_file.parent.mkdir(parents=True, exist_ok=True)- opts_file.symlink_to(project_dir / ".specify" / "does-not-exist.json")-- assert not opts_file.exists() # sanity: this is what makes it dangling- assert opts_file.is_symlink()- assert resolve_active_agent_for_registration(project_dir) is None---class TestPresetSkills:- """Tests for preset skill registration and unregistration.-- Tests that install the self-test preset use ``install_self_test_preset``- which scopes a narrow filter to the expected wrap-strategy warning.- Reconciliation failures remain audible so real regressions surface.- """-- def _write_init_options(self, project_dir, ai="claude", ai_skills=True, script="sh"):- from specify_cli import save_init_options-- save_init_options(project_dir, {"ai": ai, "ai_skills": ai_skills, "script": script})-- def _create_skill(self, skills_dir, skill_name, body="original body"):- skill_dir = skills_dir / skill_name- skill_dir.mkdir(parents=True, exist_ok=True)- (skill_dir / "SKILL.md").write_text(- f"---\nname: {skill_name}\n---\n\n{body}\n"- )- return skill_dir-- def _create_command_preset(self, temp_dir, preset_id, command_name, description, body):- preset_dir = temp_dir / preset_id- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- command_file = f"{command_name}.md"- (preset_dir / "commands" / command_file).write_text(- f"---\ndescription: {description}\n---\n\n{body}\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": preset_id,- "name": preset_id,- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": command_name,- "file": f"commands/{command_file}",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)- return preset_dir-- def _create_multi_command_preset(self, temp_dir, preset_id, command_names):- """Install-directory helper for a preset with more than one command.-- Used to prove partial-result handling: a command's own template- entry can genuinely be skipped by registration (missing source- file, safety-validation rejection) while sibling commands in the- same preset still succeed.- """- preset_dir = temp_dir / preset_id- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- templates = []- for command_name in command_names:- command_file = f"{command_name}.md"- (preset_dir / "commands" / command_file).write_text(- f"---\ndescription: {command_name} test command\n---\n\n"- f"{command_name} body\n"- )- templates.append({- "type": "command",- "name": command_name,- "file": f"commands/{command_file}",- })- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": preset_id,- "name": preset_id,- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {"templates": templates},- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)- return preset_dir-- def _create_multi_command_preset_with_aliases(self, temp_dir, preset_id, command_specs):- """Install-directory helper for a preset whose commands carry aliases.-- ``command_specs`` is a list of ``(primary_name, [alias, ...])``- tuples. Each command gets its own source file (aliases share the- same source/content as their primary β CommandRegistrar renders- them from the same command file, just under a different output- name (#2948)).- """- preset_dir = temp_dir / preset_id- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- templates = []- for primary_name, aliases in command_specs:- command_file = f"{primary_name}.md"- (preset_dir / "commands" / command_file).write_text(- f"---\ndescription: {primary_name} test command\n---\n\n"- f"{primary_name} body\n"- )- templates.append({- "type": "command",- "name": primary_name,- "file": f"commands/{command_file}",- "aliases": list(aliases),- })- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": preset_id,- "name": preset_id,- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {"templates": templates},- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)- return preset_dir-- def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):- """When skills mode was used, a preset command override should update the skill."""- # Simulate skills mode having been used: write init-options + create skill- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # Also create the claude commands dir so commands get registered- (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)-- # Install self-test preset (has a command override for speckit.specify)- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:self-test" in content, "Skill should reference preset source"- assert "disable-model-invocation: false" in content-- # Verify it was recorded in registry, keyed by the active agent- metadata = manager.registry.get("self-test")- assert "speckit-specify" in metadata.get("registered_skills", {}).get("claude", [])-- def _install_arg_hint_preset(self, project_dir, temp_dir, ai, skills_dir, description, arg_hint):- """Install a preset whose command declares argument-hint; return the SKILL.md path."""- self._write_init_options(project_dir, ai=ai)- self._create_skill(skills_dir, "speckit-hinttest-cmd")- (project_dir / ".specify" / "extensions" / "hinttest").mkdir(parents=True, exist_ok=True)-- preset_dir = temp_dir / f"hint-preset-{ai}"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.hinttest.cmd.md").write_text(- "---\n"- f'description: "{description}"\n'- f'argument-hint: "{arg_hint}"\n'- "---\n\n"- "Preset command body.\n",- encoding="utf-8",- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": f"hint-preset-{ai}",- "name": "Hint Preset",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.hinttest.cmd",- "file": "commands/speckit.hinttest.cmd.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- return skills_dir / "speckit-hinttest-cmd" / "SKILL.md"-- def test_argument_hint_preserved_for_preset_command(self, project_dir, temp_dir):- """argument-hint from a preset command must survive into the SKILL.md.-- Follow-up to #2903/#2916 for the preset skill generator. The- description is long enough to fold across lines when serialized,- guarding against an in-place string injection that would split the- folded scalar into invalid YAML.- """- long_description = (- "Build and maintain a lean, static context/ knowledge folder so "- "coding agents load only what is relevant and save tokens"- )- arg_hint = "<init | update | list | check> [area] [slug] [-- notes]"- skills_dir = project_dir / ".claude" / "skills"-- skill_file = self._install_arg_hint_preset(- project_dir, temp_dir, "claude", skills_dir, long_description, arg_hint- )- assert skill_file.exists()- parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])- assert parsed["argument-hint"] == arg_hint- assert parsed["description"] == long_description-- def test_argument_hint_not_added_for_non_claude_preset_command(self, project_dir, temp_dir):- """Non-Claude skills agents must not receive argument-hint in preset skills."""- arg_hint = "<init | update | list | check> [area]"- skills_dir = project_dir / ".agents" / "skills"-- skill_file = self._install_arg_hint_preset(- project_dir, temp_dir, "codex", skills_dir, "Build context", arg_hint- )- assert skill_file.exists()- parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])- assert "argument-hint" not in parsed-- def test_wrap_preset_inherits_argument_hint_from_core(self, project_dir, temp_dir):- """A wrap-strategy preset that omits argument-hint must inherit it from the core template.-- Regression for issue #3991: the wrap-composition path in _register_skills- previously inherited only scripts/agent_scripts from core_frontmatter,- silently discarding argument-hint and leaking its value into description.- """- core_arg_hint = "Describe the feature you want to specify"- preset_description = "Wrapped speckit.specify β extra project context added"- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # Place a core template that declares argument-hint- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\n"- "description: Core specify description.\n"- f'argument-hint: "{core_arg_hint}"\n'- "---\n\n"- "Core specify body.\n",- encoding="utf-8",- )-- # Wrap preset: only declares description (no argument-hint)- preset_dir = temp_dir / "wrap-hint-preset"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.specify.md").write_text(- "---\n"- f'description: "{preset_description}"\n'- "strategy: wrap\n"- "---\n\n"- "{CORE_TEMPLATE}\n",- encoding="utf-8",- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "wrap-hint-preset",- "name": "Wrap Hint Preset",- "version": "1.0.0",- "description": "Test wrap hint inheritance",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- "strategy": "wrap",- }- ]- },- }- import yaml as _yaml- with open(preset_dir / "preset.yml", "w") as f:- _yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "1.0.0")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert skill_file.exists()- parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])- # argument-hint must be inherited from core, not dropped- assert parsed.get("argument-hint") == core_arg_hint, (- f"argument-hint was not inherited from core; parsed={parsed}"- )- # description must be exactly the preset's declared value, not concatenated- assert parsed["description"] == preset_description, (- f"description was corrupted; parsed={parsed}"- )-- def test_wrap_preset_inherits_argument_hint_for_unmapped_command(self, project_dir, temp_dir):- """Wrap inheritance must carry argument-hint for a command NOT in ARGUMENT_HINTS.-- Regression guard for issue #3991. The companion test above wraps- ``speckit.specify``, whose stem is in Claude's ``ARGUMENT_HINTS`` map, so- the string-injection fallback in ``post_process_skill_content`` re-adds- ``argument-hint`` even when wrap composition drops it β masking the bug.- This test wraps an extension-like command (``speckit.myfeature``) that is- absent from that map, so the *only* thing that can carry the hint into the- SKILL.md is the wrap-composition inheritance fix itself. Without the fix- the key is dropped and this test fails.- """- core_arg_hint = "Custom hint that lives only on the core template"- preset_description = "Wrapped speckit.myfeature β extra project context added"- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-myfeature")-- # Place a core template (extension-like command) that declares argument-hint- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "myfeature.md").write_text(- "---\n"- "description: Core myfeature description.\n"- f'argument-hint: "{core_arg_hint}"\n'- "---\n\n"- "Core myfeature body.\n",- encoding="utf-8",- )-- # Wrap preset: only declares description (no argument-hint)- preset_dir = temp_dir / "wrap-hint-preset-unmapped"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.myfeature.md").write_text(- "---\n"- f'description: "{preset_description}"\n'- "strategy: wrap\n"- "---\n\n"- "{CORE_TEMPLATE}\n",- encoding="utf-8",- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "wrap-hint-preset-unmapped",- "name": "Wrap Hint Preset Unmapped",- "version": "1.0.0",- "description": "Test wrap hint inheritance for an unmapped command",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.myfeature",- "file": "commands/speckit.myfeature.md",- "strategy": "wrap",- }- ]- },- }- import yaml as _yaml- with open(preset_dir / "preset.yml", "w") as f:- _yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "1.0.0")-- skill_file = skills_dir / "speckit-myfeature" / "SKILL.md"- assert skill_file.exists()- parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])- # argument-hint must be inherited from core, not dropped- assert parsed.get("argument-hint") == core_arg_hint, (- f"argument-hint was not inherited from core; parsed={parsed}"- )- # description must be exactly the preset's declared value, not concatenated- assert parsed["description"] == preset_description, (- f"description was corrupted; parsed={parsed}"- )-- def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):- """Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).-- ``_register_skills()`` previously ran only ``resolve_skill_placeholders()``,- so command cross-references leaked into SKILL.md as raw placeholders- instead of rendering as ``/speckit-<cmd>`` like the command layer.- """- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir,- "cmdref-install",- "speckit.specify",- "Override specify",- "Run `__SPECKIT_COMMAND_SPECIFY__` then `__SPECKIT_COMMAND_PLAN__`.\n",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked into SKILL.md"- # Claude's invoke_separator is "-", so tokens render as /speckit-<cmd>.- assert "/speckit-specify" in content- assert "/speckit-plan" in content-- def test_restore_skill_resolves_command_refs(self, project_dir, temp_dir):- """Skill restore on preset removal must also resolve command tokens (issue #2717)."""- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\n"- "Then run `__SPECKIT_COMMAND_PLAN__`.\n"- )-- preset_dir = self._create_command_preset(- temp_dir,- "cmdref-restore",- "speckit.specify",- "Override specify",- "Override body\n",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.remove("cmdref-restore")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on restore"- assert "/speckit-plan" in content-- def test_restore_skill_preserves_dollar_command_refs(self, project_dir, temp_dir):- """Dollar-style core refs remain native when a preset skill is removed."""- self._write_init_options(project_dir, ai="zcode")- skills_dir = project_dir / ".zcode" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- raw_core = (- "---\ndescription: Core specify\n---\n\n"- "Then run `__SPECKIT_COMMAND_PLAN__`.\n"- )- (core_cmds / "specify.md").write_text(raw_core)-- preset_dir = self._create_command_preset(- temp_dir,- "dollar-cmdref-restore",- "speckit.specify",- "Override specify",- "Override body\n",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.remove("dollar-cmdref-restore")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "$speckit-plan" in content- assert "/speckit-plan" not in content-- def test_reconcile_override_skill_resolves_command_refs(self, project_dir, temp_dir):- """Reconcile's project-override restore must resolve command tokens (issue #2717).-- When a preset that overrode a command is removed and a project override- becomes the winning layer, ``_reconcile_skills`` rewrites the skill from- the override body β which must also render ``__SPECKIT_COMMAND_*__`` tokens.- """- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # Project override wins once the preset is removed; its body carries a- # command cross-reference token. No core template exists for "specify",- # so the skill is restored exclusively via the reconcile override branch.- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True, exist_ok=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override specify\n---\n\n"- "Then run `__SPECKIT_COMMAND_PLAN__`.\n"- )-- preset_dir = self._create_command_preset(- temp_dir,- "cmdref-reconcile",- "speckit.specify",- "Preset specify",- "Preset body\n",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.remove("cmdref-reconcile")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "override:speckit.specify" in content, "skill should be restored from the project override"- assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on reconcile"- assert "/speckit-plan" in content-- def test_extension_restore_resolves_command_refs(self, project_dir, temp_dir):- """Extension-backed skill restore must resolve command tokens (issue #2717).-- When a preset override is removed and the skill is restored from an- extension command body, ``__SPECKIT_COMMAND_*__`` tokens in that body- must render as slash-command invocations like the core-template path.- """- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "commands" / "cmd.md").write_text(- "---\ndescription: Extension fakeext cmd\n---\n\n"- "Then run `__SPECKIT_COMMAND_PLAN__`.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- preset_dir = self._create_command_preset(- temp_dir,- "cmdref-ext-restore",- "speckit.fakeext.cmd",- "Override fakeext cmd",- "Override body\n",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.remove("cmdref-ext-restore")-- content = (skills_dir / "speckit-fakeext-cmd" / "SKILL.md").read_text()- assert "source: extension:fakeext" in content, "skill should be restored from the extension"- assert "__SPECKIT_COMMAND_" not in content, "raw command token leaked on extension restore"- assert "/speckit-plan" in content-- def test_core_command_override_skill_uses_preset_command_description(self, project_dir, temp_dir):- """Preset skill overrides for core commands should keep preset frontmatter descriptions."""- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-taskstoissues")-- preset_dir = temp_dir / "taskstoissues-description"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.repro.taskstoissues.md").write_text(- "---\n"- "description: COMMAND-FRONTMATTER-DESCRIPTION\n"- "---\n\n"- "# Repro command body\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "taskstoissues-description",- "name": "Taskstoissues Description",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.taskstoissues",- "file": "commands/speckit.repro.taskstoissues.md",- "description": "MANIFEST-DESCRIPTION",- "replaces": "speckit.taskstoissues",- "strategy": "replace",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"- content = skill_file.read_text()- assert "description: COMMAND-FRONTMATTER-DESCRIPTION" in content- assert "Convert tasks from tasks.md into GitHub issues." not in content- assert "source: preset:taskstoissues-description" in content-- def test_core_skill_restore_uses_core_command_description(self, project_dir, temp_dir):- """Core skill restore should keep core command frontmatter descriptions."""- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-taskstoissues")-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "taskstoissues.md").write_text(- "---\n"- "description: CORE-FRONTMATTER-DESCRIPTION\n"- "---\n\n"- "core taskstoissues body\n"- )- preset_dir = self._create_command_preset(- temp_dir,- "taskstoissues-restore",- "speckit.taskstoissues",- "PRESET-FRONTMATTER-DESCRIPTION",- "preset taskstoissues body\n",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.remove("taskstoissues-restore")-- skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"- content = skill_file.read_text()- assert "description: CORE-FRONTMATTER-DESCRIPTION" in content- assert "Convert tasks from tasks.md into GitHub issues." not in content- assert "source: templates/commands/taskstoissues.md" in content- assert "core taskstoissues body" in content-- def test_override_skill_reconcile_uses_override_command_description(self, project_dir, temp_dir):- """Override skill reconciliation should keep override frontmatter descriptions."""- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-taskstoissues")-- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.taskstoissues.md").write_text(- "---\n"- "description: OVERRIDE-FRONTMATTER-DESCRIPTION\n"- "---\n\n"- "override taskstoissues body\n"- )- preset_dir = self._create_command_preset(- temp_dir,- "taskstoissues-reconcile",- "speckit.taskstoissues",- "PRESET-FRONTMATTER-DESCRIPTION",- "preset taskstoissues body\n",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-taskstoissues" / "SKILL.md"- content = skill_file.read_text()- assert "description: OVERRIDE-FRONTMATTER-DESCRIPTION" in content- assert "Convert tasks from tasks.md into GitHub issues." not in content- assert "source: override:speckit.taskstoissues" in content- assert "override taskstoissues body" in content-- def test_skill_not_updated_when_ai_skills_disabled(self, project_dir, temp_dir):- """When skills mode was NOT used, preset install should not touch skills."""- self._write_init_options(project_dir, ai="qwen", ai_skills=False)- skills_dir = project_dir / ".qwen" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="untouched")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- content = skill_file.read_text()- assert "untouched" in content, "Skill should not be modified when ai_skills=False"-- def test_get_skills_dir_returns_none_for_non_string_ai(self, project_dir):- """Corrupted init-options ai values should not crash preset skill resolution."""- init_options = project_dir / ".specify" / "init-options.json"- init_options.parent.mkdir(parents=True, exist_ok=True)- init_options.write_text('{"ai":["codex"],"ai_skills":true,"script":"sh"}')-- manager = PresetManager(project_dir)-- assert manager._get_skills_dir() is None-- def test_get_skills_dir_returns_none_for_non_dict_init_options(self, project_dir):- """Corrupted non-dict init-options payloads should fail closed."""- init_options = project_dir / ".specify" / "init-options.json"- init_options.parent.mkdir(parents=True, exist_ok=True)- init_options.write_text("[]")-- manager = PresetManager(project_dir)-- assert manager._get_skills_dir() is None-- def test_skill_not_updated_without_init_options(self, project_dir, temp_dir):- """When no init-options.json exists, preset install should not touch skills."""- skills_dir = project_dir / ".qwen" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="untouched")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- file_content = skill_file.read_text()- assert "untouched" in file_content-- def test_skill_restored_on_preset_remove(self, project_dir, temp_dir):- """When a preset is removed, skills should be restored from core templates."""- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)-- # Set up core command template in the project so restoration works- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text("---\ndescription: Core specify command\n---\n\nCore specify body\n")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- # Verify preset content is in the skill- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:self-test" in skill_file.read_text()-- # Remove the preset- manager.remove("self-test")-- # Skill should be restored (core specify.md template exists)- assert skill_file.exists(), "Skill should still exist after preset removal"- content = skill_file.read_text()- assert "preset:self-test" not in content, "Preset content should be gone"- assert "templates/commands/specify.md" in content, "Should reference core template"- assert "disable-model-invocation: false" in content-- def test_skill_restored_on_preset_remove_without_project_core_templates(self, project_dir):- """Removing a preset must restore core skills even when the project- has no ``.specify/templates/commands`` directory of its own β which- is the normal case, since ``specify init`` never populates it. The- real core commands live in the bundled core_pack/repo-root templates- tree, and restoration must fall back there instead of deleting the- skill outright (#3928).- """- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # The project_dir fixture's commands dir is empty, matching a real- # project β specify init never populates project-local overrides- # for unmodified core commands.- core_cmds = project_dir / ".specify" / "templates" / "commands"- assert core_cmds.exists() and not any(core_cmds.iterdir())-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:self-test" in skill_file.read_text(encoding="utf-8")-- manager.remove("self-test")-- assert skill_file.exists(), "Core skill must be restored, not deleted"- content = skill_file.read_text(encoding="utf-8")- assert "preset:self-test" not in content- assert "templates/commands/specify.md" in content- assert "Create or update the feature specification" in content-- def test_extension_wins_over_bundled_core_on_preset_remove(- self, project_dir, monkeypatch- ):- """When an installed extension owns the same skill name as a core- command, removing a preset that overrode that skill must restore it- from the extension, not silently from the bundled core template.- Extensions are resolved ahead of bundled core elsewhere, and the- bundled-core fallback added for #3928 must not replace that- higher-priority layer.-- The extension-command namespace rules (``speckit.<ext>.<command>``)- make a genuine end-to-end name collision with a core command- cumbersome to construct through real manifests, so this stubs- ``_build_extension_skill_restore_index`` to exercise the priority- ordering in ``_unregister_skills_in_dir`` directly -- the code path- under test doesn't care how the index entry was produced, only that- it wins over the bundled-core fallback when present.- """- self._write_init_options(project_dir, ai="claude")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # No project-local core template override β the normal case, and- # the one that makes the bundled-core fallback kick in at all.- core_cmds = project_dir / ".specify" / "templates" / "commands"- assert core_cmds.exists() and not any(core_cmds.iterdir())-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- ext_specify_file = extension_dir / "commands" / "specify.md"- ext_specify_file.write_text(- "---\ndescription: Extension specify command\n---\n\n"- "extension:fakeext specify body\n"- )-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:self-test" in skill_file.read_text(encoding="utf-8")-- fake_restore_index = {- "speckit-specify": {- "command_name": "speckit.fakeext.specify",- "source_file": ext_specify_file,- "source": "extension:fakeext",- "extension_id": "fakeext",- "extension_dir": extension_dir,- }- }- monkeypatch.setattr(- manager,- "_build_extension_skill_restore_index",- lambda: fake_restore_index,- )-- manager.remove("self-test")-- assert skill_file.exists()- content = skill_file.read_text(encoding="utf-8")- assert "preset:self-test" not in content- assert "source: extension:fakeext" in content- assert "extension:fakeext specify body" in content- assert "templates/commands/specify.md" not in content-- def test_skill_restored_on_remove_resolves_script_placeholders(self, project_dir):- """Core restore should resolve {SCRIPT}/{ARGS} placeholders like other skill paths."""- self._write_init_options(project_dir, ai="claude", ai_skills=True, script="sh")- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="old")- (project_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\n"- "description: Core specify command\n"- "scripts:\n"- " sh: .specify/scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n"- "---\n\n"- "Run:\n"- "{SCRIPT}\n"- )-- manager = PresetManager(project_dir)- install_self_test_preset(manager)- manager.remove("self-test")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "{SCRIPT}" not in content- assert "{ARGS}" not in content- assert ".specify/scripts/bash/create-new-feature.sh --json \"$ARGUMENTS\"" in content-- def test_skill_not_overridden_when_skill_path_is_file(self, project_dir):- """Preset install should skip non-directory skill targets."""- self._write_init_options(project_dir, ai="qwen")- skills_dir = project_dir / ".qwen" / "skills"- skills_dir.mkdir(parents=True, exist_ok=True)- (skills_dir / "speckit-specify").write_text("not-a-directory")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- assert (skills_dir / "speckit-specify").is_file()- metadata = manager.registry.get("self-test")- assert "speckit-specify" not in metadata.get("registered_skills", {}).get("qwen", [])-- def test_no_skills_registered_when_skills_mode_disabled(self, project_dir, temp_dir):- """Skills should not be created when skills mode is disabled."""- self._write_init_options(project_dir, ai="claude", ai_skills=False)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- metadata = manager.registry.get("self-test")- assert metadata.get("registered_skills", {}) == {}-- def test_extension_skill_override_matches_hyphenated_multisegment_name(self, project_dir, temp_dir):- """Preset overrides for speckit.<ext>.<cmd> should target speckit-<ext>-<cmd> skills."""- self._write_init_options(project_dir, ai="codex")- skills_dir = project_dir / ".agents" / "skills"- self._create_skill(skills_dir, "speckit-fakeext-cmd", body="untouched")- (project_dir / ".specify" / "extensions" / "fakeext").mkdir(parents=True, exist_ok=True)-- preset_dir = temp_dir / "ext-skill-override"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-override\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "ext-skill-override",- "name": "Ext Skill Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:ext-skill-override" in content- assert "name: speckit-fakeext-cmd" in content- assert "# Speckit Fakeext Cmd Skill" in content-- metadata = manager.registry.get("ext-skill-override")- assert "speckit-fakeext-cmd" in metadata.get("registered_skills", {}).get("codex", [])-- def test_extension_skill_restored_on_preset_remove(self, project_dir, temp_dir):- """Preset removal should restore an extension-backed skill instead of deleting it."""- self._write_init_options(project_dir, ai="codex")- skills_dir = project_dir / ".agents" / "skills"- self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")- (extension_dir / "commands" / "cmd.md").write_text(- "---\n"- "description: Extension fakeext cmd\n"- "scripts:\n"- " sh: ../../scripts/bash/setup-plan.sh --json \"{ARGS}\"\n"- "---\n\n"- "extension:fakeext\n"- "Run {SCRIPT}\n"- "Read agents/control/commander.md for context.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "author": "acme-corp",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- preset_dir = temp_dir / "ext-skill-restore"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-restore\n"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": "ext-skill-restore",- "name": "Ext Skill Restore",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"- assert "preset:ext-skill-restore" in skill_file.read_text()-- manager.remove("ext-skill-restore")-- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:ext-skill-restore" not in content- assert "source: extension:fakeext" in content- assert "extension:fakeext" in content- assert '.specify/scripts/bash/setup-plan.sh --json "$ARGUMENTS"' in content- # Extension-relative subdir references must resolve to their- # installed location on restore too (#2101), not just on first- # registration.- assert ".specify/extensions/fakeext/agents/control/commander.md" in content- assert "Read agents/control" not in content- assert "# Fakeext Cmd Skill" in content-- assert yaml.safe_load(content.split("---", 2)[1])["metadata"]["author"] == "acme-corp"-- def test_skill_composed_over_extension_base_rewrites_subdir_paths(- self, project_dir, temp_dir- ):- """When a preset composes (append) over an extension-provided base- command, the resulting skill (read from the .composed output) must- still resolve the extension's own subdir references (#2101), not- just when the extension wins outright (replace)."""- self._write_init_options(project_dir, ai="codex")- skills_dir = project_dir / ".agents" / "skills"- self._create_skill(skills_dir, "speckit-fakeext-cmd", body="original extension skill")-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")- (extension_dir / "commands" / "cmd.md").write_text(- "---\ndescription: Extension fakeext cmd\n---\n\n"- "Read agents/control/commander.md for context.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- preset_dir = temp_dir / "ext-base-append-skill"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Preset overlay\n---\n\n## Extra\n"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": "ext-base-append-skill",- "name": "Ext Base Append Skill",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- "strategy": "append",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-fakeext-cmd" / "SKILL.md"- content = skill_file.read_text()- assert ".specify/extensions/fakeext/agents/control/commander.md" in content- assert "Read agents/control" not in content- assert "## Extra" in content-- def test_preset_remove_skips_skill_dir_without_skill_file(self, project_dir, temp_dir):- """Preset removal should not delete arbitrary directories missing SKILL.md."""- self._write_init_options(project_dir, ai="codex")- skills_dir = project_dir / ".agents" / "skills"- stray_skill_dir = skills_dir / "speckit-fakeext-cmd"- stray_skill_dir.mkdir(parents=True, exist_ok=True)- note_file = stray_skill_dir / "notes.txt"- note_file.write_text("user content", encoding="utf-8")-- preset_dir = temp_dir / "ext-skill-missing-file"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\n\npreset:ext-skill-missing-file\n"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": "ext-skill-missing-file",- "name": "Ext Skill Missing File",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)-- manager = PresetManager(project_dir)- installed_preset_dir = manager.presets_dir / "ext-skill-missing-file"- shutil.copytree(preset_dir, installed_preset_dir)- manager.registry.add(- "ext-skill-missing-file",- {- "version": "1.0.0",- "source": str(preset_dir),- "provides_templates": ["speckit.fakeext.cmd"],- "registered_skills": ["speckit-fakeext-cmd"],- "priority": 10,- },- )-- manager.remove("ext-skill-missing-file")-- assert stray_skill_dir.is_dir()- assert note_file.read_text(encoding="utf-8") == "user content"-- def test_kimi_legacy_dotted_skill_override_still_applies(self, project_dir, temp_dir):- """Preset overrides should still target legacy dotted-named skill dirs.-- This exercises legacy *naming* (``speckit.specify``) under the current- ``.kimi-code/`` base β distinct from the legacy ``.kimi/`` *location*.- """- self._write_init_options(project_dir, ai="kimi")- skills_dir = project_dir / ".kimi-code" / "skills"- self._create_skill(skills_dir, "speckit.specify", body="untouched")-- (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit.specify" / "SKILL.md"- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:self-test" in content- assert "name: speckit.specify" in content-- metadata = manager.registry.get("self-test")- assert "speckit.specify" in metadata.get("registered_skills", {}).get("kimi", [])-- def test_kimi_legacy_dotted_skill_reconciles_priority_winner(- self, project_dir, temp_dir- ):- """Reconciliation must carry forward recorded legacy skill names."""- self._write_init_options(project_dir, ai="kimi")- skills_dir = project_dir / ".kimi-code" / "skills"- self._create_skill(skills_dir, "speckit.specify", body="untouched")- (project_dir / ".kimi-code" / "commands").mkdir(- parents=True, exist_ok=True- )-- higher_dir = self._create_command_preset(- temp_dir,- "higher-kimi-preset",- "speckit.specify",- "Higher preset",- "Higher body",- )- lower_dir = self._create_command_preset(- temp_dir,- "lower-kimi-preset",- "speckit.specify",- "Lower preset",- "Lower body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)-- skill_file = skills_dir / "speckit.specify" / "SKILL.md"- for preset_id in ("higher-kimi-preset", "lower-kimi-preset"):- manager.registry.update(- preset_id,- {"registered_skills": {"kimi": ["speckit.specify"]}},- )- skill_file.write_text(- "---\nname: speckit.specify\n---\n\nLower body\n",- encoding="utf-8",- )- manager._reconcile_skills(["speckit.specify"])-- assert "Higher body" in skill_file.read_text(encoding="utf-8"), (- "reconciliation must replace lower-priority raw content in a "- "recorded legacy dotted skill directory"- )-- def test_kimi_legacy_dotted_skill_receives_project_override(- self, project_dir, temp_dir- ):- """Project overrides must update the recorded legacy path in place."""- self._write_init_options(project_dir, ai="kimi")- skills_dir = project_dir / ".kimi-code" / "skills"- self._create_skill(skills_dir, "speckit.specify", body="untouched")- (project_dir / ".kimi-code" / "commands").mkdir(- parents=True, exist_ok=True- )-- preset_dir = self._create_command_preset(- temp_dir,- "kimi-override-preset",- "speckit.specify",- "Preset",- "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.registry.update(- "kimi-override-preset",- {"registered_skills": {"kimi": ["speckit.specify"]}},- )- modern_skill_dir = skills_dir / "speckit-specify"- if modern_skill_dir.exists():- shutil.rmtree(modern_skill_dir)-- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",- )-- manager._reconcile_skills(["speckit.specify"])-- legacy_file = skills_dir / "speckit.specify" / "SKILL.md"- assert "Override body" in legacy_file.read_text(encoding="utf-8")- assert not modern_skill_dir.exists(), (- "legacy-only ownership must not create an untracked modern path"- )-- def test_kimi_skill_updated_even_when_ai_skills_disabled(self, project_dir, temp_dir):- """Kimi presets should still propagate command overrides to existing skills."""- self._write_init_options(project_dir, ai="kimi", ai_skills=False)- skills_dir = project_dir / ".kimi-code" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="untouched")-- (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:self-test" in content- assert "name: speckit-specify" in content-- metadata = manager.registry.get("self-test")- assert "speckit-specify" in metadata.get("registered_skills", {}).get("kimi", [])-- def test_kimi_new_skill_created_even_when_ai_skills_disabled(self, project_dir, temp_dir):- """Kimi native skills should still receive brand-new preset commands."""- self._write_init_options(project_dir, ai="kimi", ai_skills=False)- skills_dir = project_dir / ".kimi-code" / "skills"- skills_dir.mkdir(parents=True, exist_ok=True)-- preset_dir = temp_dir / "kimi-new-skill"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.research.md").write_text(- "---\n"- "description: Kimi research workflow\n"- "---\n\n"- "preset:kimi-new-skill\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "kimi-new-skill",- "name": "Kimi New Skill",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.research",- "file": "commands/speckit.research.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-research" / "SKILL.md"- assert skill_file.exists()- content = skill_file.read_text()- assert "preset:kimi-new-skill" in content- assert "name: speckit-research" in content-- metadata = manager.registry.get("kimi-new-skill")- assert "speckit-research" in metadata.get("registered_skills", {}).get("kimi", [])-- def test_kimi_preset_skill_override_resolves_script_placeholders(self, project_dir, temp_dir):- """Kimi preset skill overrides should resolve placeholders and rewrite project paths."""- self._write_init_options(project_dir, ai="kimi", ai_skills=False, script="sh")- skills_dir = project_dir / ".kimi-code" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="untouched")- (project_dir / ".kimi-code" / "commands").mkdir(parents=True, exist_ok=True)-- preset_dir = temp_dir / "kimi-placeholder-override"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.specify.md").write_text(- "---\n"- "description: Kimi placeholder override\n"- "scripts:\n"- " sh: scripts/bash/create-new-feature.sh --json \"{ARGS}\"\n"- "---\n\n"- "Execute `{SCRIPT}` for __AGENT__\n"- "Review templates/checklist.md and memory/constitution.md\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "kimi-placeholder-override",- "name": "Kimi Placeholder Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "{SCRIPT}" not in content- assert "__AGENT__" not in content- assert ".specify/scripts/bash/create-new-feature.sh --json \"$ARGUMENTS\"" in content- assert ".specify/templates/checklist.md" in content- assert ".specify/memory/constitution.md" in content- assert "for kimi" in content-- def test_agy_skill_restored_on_preset_remove(self, project_dir, temp_dir):- """Agy preset removal should restore native skills instead of deleting them."""- self._write_init_options(project_dir, ai="agy", ai_skills=True)- skills_dir = project_dir / ".agents" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="before override")-- core_command = project_dir / ".specify" / "templates" / "commands" / "specify.md"- core_command.write_text(- "---\n"- "description: Restored core specify workflow\n"- "---\n\n"- "restored core body\n"- )-- preset_dir = temp_dir / "agy-override"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.specify.md").write_text(- "---\n"- "description: Agy override\n"- "---\n\n"- "preset agy body\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "agy-override",- "name": "Agy Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset agy body" in skill_file.read_text()-- assert manager.remove("agy-override") is True- assert skill_file.exists()- restored = skill_file.read_text()- assert "restored core body" in restored- assert "name: speckit-specify" in restored-- def test_preset_skill_registration_handles_non_dict_init_options(self, project_dir, temp_dir):- """Non-dict init-options payloads should not crash preset install/remove flows."""- init_options = project_dir / ".specify" / "init-options.json"- init_options.parent.mkdir(parents=True, exist_ok=True)- init_options.write_text("[]")-- skills_dir = project_dir / ".qwen" / "skills"- self._create_skill(skills_dir, "speckit-specify", body="untouched")-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- skill_content = (skills_dir / "speckit-specify" / "SKILL.md").read_text()- assert "untouched" in skill_content-- def test_preset_add_corrupted_init_options_fails_closed(self, project_dir, temp_dir):- """Corrupted (but present) init-options.json must not back-fill every- detected agent for preset command registration.-- Before the shared ``resolve_active_agent_for_registration`` fix,- ``load_init_options`` returning ``{}`` for a corrupted file was- indistinguishable from "no file at all", so ``_register_commands``- treated it like a legacy pre-init-options project and registered- the preset's command override for every detected agent (#2948).- """- init_options = project_dir / ".specify" / "init-options.json"- init_options.parent.mkdir(parents=True, exist_ok=True)- init_options.write_text("{not valid json", encoding="utf-8")-- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "corrupt-init-preset", "speckit.specify",- "Corrupt init test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- metadata = manager.registry.get("corrupt-init-preset")- assert metadata.get("registered_commands") == {}, (- "a corrupted init-options.json must fail closed, not "- "back-fill every detected agent (#2948)"- )- assert not list(gemini_dir.glob("*specify*")), (- "no command file should be written for any agent when "- "init-options.json is corrupted"- )-- def test_reconciliation_restricted_to_active_agent(self, project_dir, temp_dir):- """Reconciliation after install/remove must also respect the- single-active rule, not just the initial registration.-- ``_reconcile_composed_commands`` (invoked after- ``install_from_directory``/``remove``) resolves composition winners- via ``register_commands_for_non_skill_agents``, a separate code- path from ``_register_commands``'s initial registration. Before the- fix it ignored the active-agent restriction entirely and wrote the- winning content for every detected non-skill agent, leaving- untracked orphaned artifacts in inactive integrations (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- # A non-replace (append) strategy command forces reconciliation to- # run register_commands_for_non_skill_agents for every non-skill- # agent directory it detects.- preset_dir = temp_dir / "reconcile-active-only"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.specify.md").write_text(- "---\ndescription: Appended\nstrategy: append\n---\n\nAppended body\n",- encoding="utf-8",- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "reconcile-active-only",- "name": "Reconcile Active Only",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [{- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- "strategy": "append",- }]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- assert not list(gemini_dir.glob("*specify*")), (- "reconciliation must not write command files for a detected "- "but inactive non-skill agent (#2948)"- )-- def test_use_rescaffold_reconciles_project_override(self, project_dir, temp_dir):- """``integration use``/``switch`` rescaffolding must reconcile the- full priority stack, not just write each preset's own content.-- Project overrides are the highest-priority layer, above every- preset. ``register_enabled_presets_for_agent`` (invoked by- ``integration use``/``switch``) calls ``_register_commands`` for- each enabled preset directly, the same as ``install_from_directory``- β but unlike install/remove, it never followed up with- ``_reconcile_composed_commands``. Before the fix, rescaffolding a- newly activated agent could leave the preset's raw content in- place instead of resolving the real winner (the project override)- from the full stack (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True, exist_ok=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override specify\n---\n\nOverride body\n",- encoding="utf-8",- )-- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "use-reconcile-preset", "speckit.specify",- "Preset specify", "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Simulate `integration use gemini`: switch the active agent and- # rescaffold enabled presets for it, mirroring what the CLI does.- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- manager.register_enabled_presets_for_agent("gemini")-- cmd_file = gemini_dir / "speckit.specify.toml"- assert cmd_file.exists(), "sanity: gemini should get a command file at all"- content = cmd_file.read_text()- assert "Override body" in content, (- "the project override must still win after rescaffold "- "reconciliation, not the preset's raw content (#2948)"- )- assert "Preset body" not in content-- def test_hermes_rescaffold_reconciles_global_skill_output(- self, project_dir, temp_dir, monkeypatch- ):- home = temp_dir / "home"- home.mkdir()- monkeypatch.setattr(Path, "home", lambda: home)- (home / ".hermes" / "skills").mkdir(parents=True)- self._write_init_options(project_dir, ai="hermes", ai_skills=True)- (project_dir / ".hermes" / "skills").mkdir(parents=True)-- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True, exist_ok=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override specify\n---\n\nOverride body\n",- encoding="utf-8",- )-- preset_dir = self._create_command_preset(- temp_dir, "hermes-reconcile-preset", "speckit.specify",- "Preset specify", "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- manager.register_enabled_presets_for_agent("hermes")-- skill_file = (- home / ".hermes" / "skills" / "speckit-specify" / "SKILL.md"- )- assert skill_file.exists()- content = skill_file.read_text(encoding="utf-8")- assert "Override body" in content- assert "Preset body" not in content- assert not list(- (project_dir / ".hermes" / "skills").glob("speckit-*/SKILL.md")- )-- (overrides_dir / "speckit.specify.md").unlink()- assert manager.remove("hermes-reconcile-preset") is True- if skill_file.exists():- restored = skill_file.read_text(encoding="utf-8")- assert "Override body" not in restored- assert "Preset body" not in restored-- def test_rescaffold_persists_commands_before_fallible_skills_phase(- self, project_dir, temp_dir- ):- """A failure in the skills phase must not lose track of command- files the commands phase already wrote to disk.-- ``register_enabled_presets_for_agent`` computes both- ``registered_commands`` and ``registered_skills`` and persists them- together in a single ``registry.update()`` call after both phases- run. If ``_register_skills`` raises, the whole per-preset ``try``- block is caught and ``registry.update()`` is never reached β even- though ``_register_commands`` already wrote a real command file to- disk. That file becomes untracked and preset removal can no longer- clean it up. ``install_from_directory`` avoids this by persisting- ``registered_commands`` immediately after the commands phase,- before starting the independently fallible skills phase; rescaffold- must do the same (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- preset_dir = self._create_command_preset(- temp_dir, "rescaffold-persist-preset", "speckit.specify",- "Rescaffold persist test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Switch to gemini (a plain command-file agent, so _register_commands- # writes a real file) and make the *skills* phase blow up.- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_commands_dir = project_dir / ".gemini" / "commands"- gemini_commands_dir.mkdir(parents=True)-- from unittest.mock import patch-- with patch.object(- PresetManager, "_register_skills",- side_effect=RuntimeError("simulated skills failure"),- ):- manager.register_enabled_presets_for_agent("gemini")-- cmd_file = gemini_commands_dir / "speckit.specify.toml"- assert cmd_file.exists(), (- "sanity: the commands phase must have written the file before "- "the skills phase raised"- )-- metadata = manager.registry.get("rescaffold-persist-preset")- assert metadata["registered_commands"].get("gemini"), (- "registered_commands must be persisted immediately after the "- "commands phase, not only after the (fallible) skills phase "- "also succeeds β otherwise the file written above is untracked "- "and preset removal can't clean it up (#2948)"- )-- def test_rescaffold_reconciles_override_even_when_skills_phase_fails(- self, project_dir, temp_dir- ):- """A project override must still win after rescaffold even if the- independently-fallible skills phase raises for that preset.-- ``register_enabled_presets_for_agent`` only records a preset's- command names into ``affected_cmd_names`` β the set later passed to- ``_reconcile_composed_commands``/``_reconcile_skills`` β in the- ``for tmpl in manifest.templates`` loop that runs *after*- ``_register_skills`` inside the per-preset ``try`` block. If- ``_register_skills`` raises, the per-preset ``except`` catches it- and ``continue``s before that loop ever runs, so this preset's- command names never make it into ``affected_cmd_names`` even though- ``_register_commands`` already wrote its raw content to disk. The- final reconciliation call is skipped for this preset entirely,- leaving the raw preset content in place instead of the project- override that should win (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True, exist_ok=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override specify\n---\n\nOverride body\n",- encoding="utf-8",- )-- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "reconcile-despite-skills-failure", "speckit.specify",- "Preset specify", "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Simulate `integration use gemini` with the skills phase failing- # for this preset (e.g. a symlink/permission error unrelated to the- # commands phase, which already succeeded).- self._write_init_options(project_dir, ai="gemini", ai_skills=False)-- from unittest.mock import patch-- with patch.object(- PresetManager, "_register_skills",- side_effect=RuntimeError("simulated skills failure"),- ):- manager.register_enabled_presets_for_agent("gemini")-- cmd_file = gemini_dir / "speckit.specify.toml"- assert cmd_file.exists(), "sanity: gemini should get a command file at all"- content = cmd_file.read_text()- assert "Override body" in content, (- "the project override must still win after rescaffold, even "- "though this preset's skills phase raised β a fallible skills "- "phase must not skip reconciliation for command writes that "- "already succeeded (#2948)"- )- assert "Preset body" not in content-- def test_rescaffold_reconciles_partial_command_write_after_failure(- self, project_dir, temp_dir, monkeypatch- ):- """A command written before _register_commands raises must still be- included in final priority-stack reconciliation."""- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True, exist_ok=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override specify\n---\n\nOverride body\n",- encoding="utf-8",- )-- preset_dir = self._create_command_preset(- temp_dir,- "partial-command-failure-preset",- "speckit.specify",- "Preset specify",- "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)- cmd_file = gemini_dir / "speckit.specify.toml"-- def partial_register(manifest, pack_dir):- cmd_file.write_text("Partially written preset body\n", encoding="utf-8")- raise RuntimeError("simulated partial command failure")-- monkeypatch.setattr(manager, "_register_commands", partial_register)- manager.register_enabled_presets_for_agent("gemini")-- content = cmd_file.read_text(encoding="utf-8")- assert "Override body" in content- assert "Partially written preset body" not in content-- def test_copilot_skills_mode_skips_command_registration(self, project_dir, temp_dir):- """``integration use copilot`` with skills mode enabled must only- write the SKILL.md mirror, not also copilot's static command file.-- Copilot is command-backed (``extension: ".agent.md"``), but when- ``ai_skills`` is enabled its preset overrides are meant to render- exclusively as skills via ``_register_skills``. Before the fix,- ``_register_commands`` had no ``ai_skills`` guard (unlike the- extensions path), so both a stale ``.agent.md`` command file and- the ``SKILL.md`` mirror were written for the same override (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "copilot-skills-preset", "speckit.specify",- "Copilot skills test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- assert not list(copilot_commands_dir.glob("*specify*")), (- "command-mode and skills-mode artifacts are mutually exclusive: "- "no .agent.md command file should be written when copilot is "- "running in skills mode (#2948)"- )- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:copilot-skills-preset" in skill_file.read_text()-- def test_rescaffold_toggle_command_to_skills_removes_stale_command_file(- self, project_dir, temp_dir- ):- """Toggling the *same* agent from command mode to skills mode must- remove the stale command-mode artifact, not just add the new one.-- Copilot stays the active agent throughout (``integration upgrade- copilot`` after flipping ``ai_skills``, not a switch to a different- agent). Before the fix, ``_register_commands``'s ``ai_skills`` guard- made rescaffold a no-op for the commands phase once skills mode was- on, leaving the previously written ``.agent.md`` file and its- ``registered_commands`` entry behind even though ``_register_skills``- went on to also write the ``SKILL.md`` mirror β violating the- command/skill mutual-exclusion invariant this PR otherwise enforces- (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "toggle-cmd-to-skill-preset", "speckit.specify",- "Toggle test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- assert cmd_file.exists(), (- "sanity: command mode should have written copilot's command file"- )- metadata = manager.registry.get("toggle-cmd-to-skill-preset")- assert metadata["registered_commands"].get("copilot"), (- "sanity: the command-mode write should be tracked for copilot"- )-- # Flip ai_skills on for the *same* active agent and rescaffold, as- # `integration upgrade copilot` would after the mode toggle.- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert not cmd_file.exists(), (- "the stale command-mode file must be removed once copilot has "- "toggled to skills mode for the same agent (#2948)"- )- metadata = manager.registry.get("toggle-cmd-to-skill-preset")- assert not metadata["registered_commands"].get("copilot"), (- "registered_commands must stop tracking copilot once its "- "artifact has been unregistered, or removal will try to clean "- "up a file that no longer exists (#2948)"- )- skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"- assert "preset:toggle-cmd-to-skill-preset" in skill_file.read_text(), (- "sanity: the new skills-mode artifact should still be written"- )-- def test_rescaffold_scaffolds_selfcontained_namespaced_commands(- self, project_dir, temp_dir- ):- """A self-contained ``speckit.<ns>.<cmd>`` preset command scaffolds and- survives rescaffold, even when no matching extension is installed.-- The preset ships the command body itself, so it is materialized just- like a short ``speckit.<cmd>`` command β both at install and through a- later reconciliation/rescaffold pass. It is not dropped by the- ``speckit.<ns>.<cmd>`` name shape (#4076).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "ext-scoped-preset", "speckit.git.feature",- "Ext override", "ext body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- ext_cmd = commands_dir / "speckit.git.feature.agent.md"- assert ext_cmd.exists(), (- "sanity: install must scaffold a self-contained namespaced command "- "even when its like-named extension isn't installed"- )-- manager.register_enabled_presets_for_agent("copilot")-- assert ext_cmd.exists(), (- "rescaffold must keep the self-contained namespaced command"- )- metadata = manager.registry.get("ext-scoped-preset")- assert (metadata.get("registered_commands") or {}).get("copilot")-- def test_rescaffold_scaffolds_selfcontained_namespaced_skills(- self, project_dir, temp_dir- ):- """A self-contained ``speckit.<ns>.<cmd>`` preset command renders its- skill even when no matching extension is installed."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- skills_dir = project_dir / ".github" / "skills"- skills_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir,- "ext-scoped-skill-preset",- "speckit.git.feature",- "Ext override",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_name = "speckit-git-feature"- skill_file = skills_dir / skill_name / "SKILL.md"- assert skill_file.exists(), (- "install must render a self-contained namespaced command's skill "- "even when its like-named extension isn't installed"- )-- manager.register_enabled_presets_for_agent("copilot")-- assert skill_file.exists(), (- "rescaffold must keep the self-contained namespaced command's skill"- )-- def test_uncomposable_wrap_command_skips_skill_in_skills_mode(- self, project_dir, temp_dir- ):- """A wrap command with no base layer must not materialize a broken- skill in skills mode.-- When ``_register_commands`` skips an uncomposable wrap command (no- base to compose onto β e.g. the command it wraps comes from an- uninstalled extension), ``_register_skills`` must skip it too. Before- this fix, skills mode fell back to the raw preset body and wrote a- SKILL.md containing a literal ``{CORE_TEMPLATE}`` placeholder.- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- skills_dir = project_dir / ".github" / "skills"- skills_dir.mkdir(parents=True)-- preset_dir = temp_dir / "uncomposable-wrap"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- # speckit.git.feature has no core command template and no installed- # extension, so there is no base layer to wrap.- (preset_dir / "commands" / "speckit.git.feature.md").write_text(- "---\ndescription: Wrap\nstrategy: wrap\n---\n\n"- "wrap start\n{CORE_TEMPLATE}\nwrap end\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "uncomposable-wrap",- "name": "uncomposable-wrap",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.git.feature",- "file": "commands/speckit.git.feature.md",- "strategy": "wrap",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="no base command layer"):- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-git-feature" / "SKILL.md"- assert not skill_file.exists(), (- "an uncomposable wrap command must not be rendered as a skill"- )- # Belt-and-suspenders: no artifact anywhere may leak the raw placeholder.- leaked = [- p for p in skills_dir.rglob("*")- if p.is_file() and "{CORE_TEMPLATE}" in p.read_text(encoding="utf-8")- ]- assert not leaked, f"literal {{CORE_TEMPLATE}} leaked into {leaked}"-- def test_same_mode_partial_command_rescaffold_keeps_skipped_tracking(- self, project_dir, temp_dir- ):- """A partial command refresh must keep still-live skipped artifacts tracked."""- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)- preset_dir = self._create_multi_command_preset(- temp_dir,- "same-mode-partial-command-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- installed_dir = manager.presets_dir / "same-mode-partial-command-preset"- (installed_dir / "commands" / "speckit.plan.md").unlink()- manager.register_enabled_presets_for_agent("copilot")-- metadata = manager.registry.get("same-mode-partial-command-preset")- assert set(metadata["registered_commands"]["copilot"]) == {- "speckit.specify",- "speckit.plan",- }- assert (commands_dir / "speckit.plan.agent.md").exists()-- def test_same_mode_partial_skill_rescaffold_keeps_skipped_tracking(- self, project_dir, temp_dir- ):- """A partial skill refresh must keep still-live skipped artifacts tracked."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")- self._create_skill(skills_dir, "speckit-plan")- preset_dir = self._create_multi_command_preset(- temp_dir,- "same-mode-partial-skill-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- installed_dir = manager.presets_dir / "same-mode-partial-skill-preset"- (installed_dir / "commands" / "speckit.plan.md").unlink()- manager.register_enabled_presets_for_agent("copilot")-- metadata = manager.registry.get("same-mode-partial-skill-preset")- assert set(metadata["registered_skills"]["copilot"]) == {- "speckit-specify",- "speckit-plan",- }-- def test_toggle_command_to_skills_preserves_old_command_on_skills_failure(- self, project_dir, temp_dir, monkeypatch- ):- """A command->skills toggle must not destroy the old command- artifact before the new skill registration has actually succeeded.-- Before the fix, the stale command-mode file/tracking was- unregistered unconditionally as soon as ``_register_commands``'s- ``ai_skills`` guard made the commands phase a no-op β regardless- of whether the subsequent, independently-fallible- ``_register_skills()`` call actually succeeded. If skills raises- (e.g. a transient I/O error), the per-preset exception handler- just logs and continues, leaving neither the old command file- nor a new skill file β the preset's command override vanishes- entirely from copilot until the next successful rescaffold- (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "toggle-failure-preset", "speckit.specify",- "Toggle failure test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- assert cmd_file.exists(), (- "sanity: command mode should have written copilot's command file"- )- metadata = manager.registry.get("toggle-failure-preset")- assert metadata["registered_commands"].get("copilot"), (- "sanity: the command-mode write should be tracked for copilot"- )-- # Flip ai_skills on for the *same* active agent and rescaffold, as- # `integration upgrade copilot` would, but with skills registration- # injected to fail.- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- def _raise_register_skills(*args, **kwargs):- raise OSError("simulated skills-phase failure")-- monkeypatch.setattr(manager, "_register_skills", _raise_register_skills)- manager.register_enabled_presets_for_agent("copilot")-- assert cmd_file.exists(), (- "the old command-mode artifact must survive when the "- "replacement skills registration fails β deleting it before "- "the new artifact is confirmed leaves neither in place (#2948)"- )- metadata = manager.registry.get("toggle-failure-preset")- assert metadata["registered_commands"].get("copilot"), (- "registered_commands must keep tracking copilot's still-live "- "command file when the skills replacement failed, or a later "- "removal/rescaffold will believe there is nothing to clean up "- "even though the file is still on disk (#2948)"- )-- def test_toggle_command_to_skills_empty_result_preserves_old_command(- self, project_dir, temp_dir- ):- """A non-raising but empty skills result must not delete the old command.-- Before the fix, the stale command-mode artifact was retired as- soon as ``_register_skills()`` completed without raising β- regardless of whether it actually wrote anything for this agent.- Deleting the preset's own command source file (simulating a- missing/corrupted override) makes ``_register_skills`` return- ``{}`` for copilot without raising at all, which must leave the- old command file and its tracking untouched (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "toggle-empty-result-preset", "speckit.specify",- "Toggle empty-result test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- assert cmd_file.exists(), (- "sanity: command mode should have written copilot's command file"- )-- # Remove the *installed* copy of the preset's source file (not the- # original temp source) so _register_skills can find nothing to- # render β a real "missing source" case, not an exception β leaving- # registered_skills empty for copilot.- (manager.presets_dir / "toggle-empty-result-preset" / "commands" / "speckit.specify.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert cmd_file.exists(), (- "an empty (non-raising) skills registration result must not "- "cause the old command-mode artifact to be deleted (#2948)"- )- metadata = manager.registry.get("toggle-empty-result-preset")- assert metadata["registered_commands"].get("copilot"), (- "registered_commands must keep tracking copilot's still-live "- "command file when nothing was actually replaced (#2948)"- )- skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"- assert not skill_file.exists(), (- "sanity: no skill should have been written when the source "- "was missing"- )-- def test_toggle_command_to_skills_partial_result_only_removes_replaced_command(- self, project_dir, temp_dir- ):- """Only the command whose skill replacement actually landed is retired.-- A two-command preset where one command's source file goes missing- right before the toggle: ``_register_skills`` genuinely returns a- partial result (one name present, one silently skipped) without- raising. The command whose skill was written must be retired; the- other must keep both its old command file and its registry- tracking, since no replacement for it actually landed (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_multi_command_preset(- temp_dir, "toggle-partial-result-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- specify_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- plan_cmd_file = copilot_commands_dir / "speckit.plan.agent.md"- assert specify_cmd_file.exists() and plan_cmd_file.exists(), (- "sanity: command mode should have written both command files"- )- metadata = manager.registry.get("toggle-partial-result-preset")- assert set(metadata["registered_commands"].get("copilot", [])) == {- "speckit.specify", "speckit.plan",- }, "sanity: both commands should be tracked for copilot"-- # Remove only the plan command's *installed* source so its skill- # replacement is silently skipped (missing source), while- # specify's succeeds β a genuine partial result, not an injected- # exception.- (manager.presets_dir / "toggle-partial-result-preset" / "commands" / "speckit.plan.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert not specify_cmd_file.exists(), (- "the specify command's old artifact must be retired since its "- "skill replacement actually landed (#2948)"- )- assert plan_cmd_file.exists(), (- "the plan command's old artifact must survive since its skill "- "replacement never landed (missing source) (#2948)"- )- metadata = manager.registry.get("toggle-partial-result-preset")- tracked_commands = metadata["registered_commands"].get("copilot", [])- assert "speckit.specify" not in tracked_commands, (- "specify must stop being tracked as a command once its "- "artifact has been unregistered (#2948)"- )- assert "speckit.plan" in tracked_commands, (- "plan must keep being tracked as a command since its old "- "artifact is still on disk (#2948)"- )- specify_skill_file = (- project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"- )- assert "preset:toggle-partial-result-preset" in specify_skill_file.read_text(), (- "sanity: specify's new skill artifact should exist"- )- plan_skill_file = project_dir / ".github" / "skills" / "speckit-plan"- assert not plan_skill_file.exists(), (- "sanity: no skill should have been written for plan since its "- "source was missing"- )-- def test_remove_after_partial_command_to_skills_toggle_keeps_skills_mode_agent_command_free(- self, project_dir, temp_dir- ):- """Removal must not recreate a command file for a skills-mode agent.-- A partially failed commandβskills toggle leaves the active agent's- stale ``registered_commands`` entry behind. Removing that preset- records the agent in ``extra_agents`` for post-removal- reconciliation, and ``register_commands_for_non_skill_agents``- admits every ``extra_agents`` member even when the active-only- ``only_agent`` guard excludes the agent β so the surviving- lower-priority preset's command file was recreated for an agent- now running in skills mode (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- lower_dir = self._create_command_preset(- temp_dir, "stale-toggle-lower-preset", "speckit.plan",- "Lower preset", "Lower body",- )- higher_dir = self._create_command_preset(- temp_dir, "stale-toggle-higher-preset", "speckit.plan",- "Higher preset", "Higher body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)-- command_file = copilot_commands_dir / "speckit.plan.agent.md"- assert "Higher body" in command_file.read_text(encoding="utf-8"), (- "sanity: command mode should have written the winning preset"- )-- # Break the higher preset's installed source so its skill- # replacement is silently skipped during the toggle β a genuine- # partial commandβskills toggle that leaves the stale- # registered_commands entry for copilot behind.- (manager.presets_dir / "stale-toggle-higher-preset" / "commands" / "speckit.plan.md").unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- metadata = manager.registry.get("stale-toggle-higher-preset")- assert "speckit.plan" in metadata["registered_commands"].get("copilot", []), (- "sanity: the partial toggle must leave the stale command "- "tracking behind"- )-- manager.remove("stale-toggle-higher-preset")-- assert not command_file.exists(), (- "removing the preset while copilot runs in skills mode must "- "not recreate its command file from the surviving lower "- "preset via the stale extra_agents entry (#2948)"- )-- def test_remove_after_partial_skills_to_command_toggle_deletes_stale_skill(- self, project_dir, temp_dir- ):- """Removal must delete, not restore, a command-mode agent's stale skill.-- The inverse partial toggle: a skillsβcommand conversion that could- not replace one command leaves that skill tracked in- ``registered_skills``. Removing the preset while the agent is now- in command mode sent it through ``_unregister_skills()``, which- restored a core/extension ``SKILL.md``, and ``extra_skills_dirs``- then let ``_reconcile_skills`` reapply the surviving lower preset β- leaving the active command-mode agent with a skill artifact it- must not have (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- lower_dir = self._create_command_preset(- temp_dir, "inverse-toggle-lower-preset", "speckit.plan",- "Lower preset", "Lower body",- )- higher_dir = self._create_command_preset(- temp_dir, "inverse-toggle-higher-preset", "speckit.plan",- "Higher preset", "Higher body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)-- skill_dir = project_dir / ".github" / "skills" / "speckit-plan"- assert (skill_dir / "SKILL.md").exists(), (- "sanity: skills mode should have written the skill"- )-- # Break the higher preset's installed source so its command- # replacement never lands during the skillsβcommand toggle,- # leaving the skill tracked for copilot.- (manager.presets_dir / "inverse-toggle-higher-preset" / "commands" / "speckit.plan.md").unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- manager.register_enabled_presets_for_agent("copilot")-- metadata = manager.registry.get("inverse-toggle-higher-preset")- registered_skills = metadata.get("registered_skills") or {}- assert registered_skills.get("copilot"), (- "sanity: the partial toggle must leave the stale skill "- "tracking behind"- )- assert (skill_dir / "SKILL.md").exists(), (- "sanity: the stale skill artifact must survive the partial toggle"- )-- manager.remove("inverse-toggle-higher-preset")-- assert not skill_dir.exists(), (- "removing the preset while copilot runs in command mode must "- "delete the stale preset-owned skill instead of restoring core "- "content or reapplying the surviving lower preset (#2948)"- )-- def test_lower_priority_skill_does_not_remove_failed_winner_command(- self, project_dir, temp_dir- ):- """Only a successfully rendered winning layer may retire a command."""- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- lower_dir = self._create_command_preset(- temp_dir,- "lower-toggle-preset",- "speckit.specify",- "Lower preset",- "Lower body",- )- higher_dir = self._create_command_preset(- temp_dir,- "higher-toggle-preset",- "speckit.specify",- "Higher preset",- "Higher body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)-- command_file = commands_dir / "speckit.specify.agent.md"- assert "Higher body" in command_file.read_text(encoding="utf-8")-- higher_source = (- manager.presets_dir- / "higher-toggle-preset"- / "commands"- / "speckit.specify.md"- )- higher_source.unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- manager.register_enabled_presets_for_agent("copilot")-- assert command_file.exists(), (- "a lower-priority skill replacement must not remove the existing "- "higher-priority command when the winning layer did not render"- )- assert "Higher body" in command_file.read_text(encoding="utf-8")-- higher_source.write_text(- "---\ndescription: Higher preset\n---\n\nHigher body\n",- encoding="utf-8",- )- manager.register_enabled_presets_for_agent("copilot")-- assert not command_file.exists(), (- "the old command should be retired after the winning skill "- "layer renders successfully"- )- for preset_id in ("lower-toggle-preset", "higher-toggle-preset"):- metadata = manager.registry.get(preset_id)- assert not metadata["registered_commands"].get("copilot"), (- "all layers sharing the retired command output must drop "- "their stale command tracking"- )-- def test_successful_winner_without_stale_tracking_retires_lower_command(- self, project_dir, temp_dir- ):- """Winner success is independent of whether that layer tracked a command."""- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- lower_dir = self._create_command_preset(- temp_dir,- "lower-command-preset",- "speckit.specify",- "Lower preset",- "Lower body",- )- higher_dir = self._create_command_preset(- temp_dir,- "higher-skill-preset",- "speckit.specify",- "Higher preset",- "Higher body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)-- command_file = commands_dir / "speckit.specify.agent.md"- assert command_file.exists()-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)- higher_metadata = manager.registry.get("higher-skill-preset")- assert not higher_metadata["registered_commands"].get("copilot")-- manager.register_enabled_presets_for_agent("copilot")-- assert not command_file.exists(), (- "a successfully rendered winning skill must retire a lower "- "layer's stale command even when the winner never tracked one"- )- lower_metadata = manager.registry.get("lower-command-preset")- assert not lower_metadata["registered_commands"].get("copilot")-- def test_lower_priority_command_does_not_remove_failed_winner_skill(- self, project_dir, temp_dir- ):- """Only a successfully rendered winning command may retire a skill."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- lower_dir = self._create_command_preset(- temp_dir,- "lower-skill-preset",- "speckit.specify",- "Lower preset",- "Lower body",- )- higher_dir = self._create_command_preset(- temp_dir,- "higher-command-preset",- "speckit.specify",- "Higher preset",- "Higher body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=20)- manager.install_from_directory(higher_dir, "0.1.5", priority=10)-- skill_file = (- project_dir- / ".github"- / "skills"- / "speckit-specify"- / "SKILL.md"- )- assert "Higher body" in skill_file.read_text(encoding="utf-8")-- higher_source = (- manager.presets_dir- / "higher-command-preset"- / "commands"- / "speckit.specify.md"- )- higher_source.unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=False)-- manager.register_enabled_presets_for_agent("copilot")-- assert skill_file.exists(), (- "a lower-priority command replacement must not remove the "- "existing higher-priority skill when the winner did not render"- )- assert "Higher body" in skill_file.read_text(encoding="utf-8")-- higher_source.write_text(- "---\ndescription: Higher preset\n---\n\nHigher body\n",- encoding="utf-8",- )- manager.register_enabled_presets_for_agent("copilot")-- assert not skill_file.exists(), (- "the old skill should be retired after the winning command "- "layer renders successfully"- )- for preset_id in ("lower-skill-preset", "higher-command-preset"):- metadata = manager.registry.get(preset_id)- assert not metadata["registered_skills"].get("copilot"), (- "all layers sharing the retired skill output must drop "- "their stale skill tracking"- )-- def test_project_override_command_retires_stale_preset_skill(- self, project_dir, temp_dir- ):- """A reconciled project override can replace a stale preset skill."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir,- "override-toggle-preset",- "speckit.specify",- "Preset",- "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = (- project_dir- / ".github"- / "skills"- / "speckit-specify"- / "SKILL.md"- )- assert skill_file.exists()-- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",- )- (- manager.presets_dir- / "override-toggle-preset"- / "commands"- / "speckit.specify.md"- ).unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=False)-- manager.register_enabled_presets_for_agent("copilot")-- command_file = commands_dir / "speckit.specify.agent.md"- assert "Override body" in command_file.read_text(encoding="utf-8")- assert not skill_file.exists(), (- "the stale preset skill must be retired once the project "- "override command is successfully reconciled"- )- metadata = manager.registry.get("override-toggle-preset")- assert not metadata["registered_skills"].get("copilot")-- def test_project_override_command_retires_reconciled_override_skill(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir,- "reconciled-override-toggle-preset",- "speckit.specify",- "Preset",- "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",- )- (- manager.presets_dir- / "reconciled-override-toggle-preset"- / "commands"- / "speckit.specify.md"- ).unlink()-- manager.register_enabled_presets_for_agent("copilot")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "override:speckit.specify" in skill_file.read_text(- encoding="utf-8"- )-- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- manager.register_enabled_presets_for_agent("copilot")-- assert "Override body" in (- commands_dir / "speckit.specify.agent.md"- ).read_text(encoding="utf-8")- assert not skill_file.exists()- metadata = manager.registry.get(- "reconciled-override-toggle-preset"- )- assert not metadata["registered_skills"].get("copilot")-- def test_project_override_skill_retires_stale_preset_command(- self, project_dir, temp_dir- ):- """A reconciled override skill may retire a stale preset command."""- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir,- "override-skill-toggle-preset",- "speckit.specify",- "Preset",- "Preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- command_file = commands_dir / "speckit.specify.agent.md"- assert command_file.exists()- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")- manager.registry.update(- "override-skill-toggle-preset",- {"registered_skills": {"copilot": ["speckit-specify"]}},- )-- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",- )- (- manager.presets_dir- / "override-skill-toggle-preset"- / "commands"- / "speckit.specify.md"- ).unlink()- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- manager.register_enabled_presets_for_agent("copilot")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "Override body" in skill_file.read_text(encoding="utf-8")- assert not command_file.exists(), (- "the stale preset command must be retired after the project "- "override skill is successfully reconciled"- )- metadata = manager.registry.get("override-skill-toggle-preset")- assert not metadata["registered_commands"].get("copilot")-- def test_partial_skill_registration_is_persisted_before_later_failure(- self, project_dir, temp_dir, monkeypatch- ):- """A successful earlier skill write remains tracked if a later read fails."""- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- commands_dir = project_dir / ".github" / "agents"- commands_dir.mkdir(parents=True)-- preset_dir = self._create_multi_command_preset(- temp_dir,- "partial-skill-failure-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- original_read_text = Path.read_text-- def fail_plan_source(path, *args, **kwargs):- if (- path.name == "speckit.plan.md"- and path.parent.name == "commands"- and "partial-skill-failure-preset" in path.parts- ):- raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid")- return original_read_text(path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", fail_plan_source)- manager.register_enabled_presets_for_agent("copilot")-- metadata = manager.registry.get("partial-skill-failure-preset")- assert "speckit-specify" in metadata["registered_skills"].get(- "copilot", []- ), (- "the first successful write must be persisted before the later "- "template failure aborts the registration call"- )- monkeypatch.setattr(Path, "read_text", original_read_text)- assert manager.remove("partial-skill-failure-preset") is True- remaining_skill = (- project_dir- / ".github"- / "skills"- / "speckit-specify"- / "SKILL.md"- )- assert (- not remaining_skill.exists()- or "preset:partial-skill-failure-preset"- not in remaining_skill.read_text(encoding="utf-8")- ), "persisted partial ownership must remain removable"-- def test_remove_cleans_native_skill_missing_from_partial_skill_map(- self, project_dir, temp_dir- ):- """Command cleanup must cover native skills absent from a partial map."""- self._write_init_options(project_dir, ai="claude", ai_skills=True)- (project_dir / ".claude" / "skills").mkdir(parents=True)- preset_dir = self._create_command_preset(- temp_dir,- "partial-agent-skill-map-preset",- "speckit.partial-native",- "Partial native skill",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- metadata = manager.registry.get("partial-agent-skill-map-preset")- assert metadata["registered_skills"].get("claude")-- self._write_init_options(project_dir, ai="codex", ai_skills=True)- (project_dir / ".agents" / "skills").mkdir(parents=True)-- from unittest.mock import patch-- with patch.object(- PresetManager,- "_register_skills",- side_effect=RuntimeError("simulated skills phase failure"),- ):- manager.register_enabled_presets_for_agent("codex")-- codex_skill = (- project_dir- / ".agents"- / "skills"- / "speckit-partial-native"- / "SKILL.md"- )- assert codex_skill.exists()- metadata = manager.registry.get("partial-agent-skill-map-preset")- assert "speckit.partial-native" in metadata[- "registered_commands"- ].get("codex", [])- assert not metadata["registered_skills"].get("codex")-- assert manager.remove("partial-agent-skill-map-preset") is True- assert not codex_skill.exists(), (- "native skill written by the commands phase must not be orphaned "- "when another agent makes registered_skills globally non-empty"- )-- def test_partial_skill_install_failure_rolls_back_persisted_writes(- self, project_dir, temp_dir, monkeypatch- ):- """Install rollback must reload partial skill ownership before removal."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- (project_dir / ".github" / "agents").mkdir(parents=True)- preset_dir = self._create_multi_command_preset(- temp_dir,- "partial-install-failure-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- original_read_text = Path.read_text-- def fail_plan_source(path, *args, **kwargs):- if (- path.name == "speckit.plan.md"- and path.parent.name == "commands"- and "partial-install-failure-preset" in path.parts- ):- raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid")- return original_read_text(path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", fail_plan_source)- with pytest.raises(UnicodeDecodeError):- manager.install_from_directory(preset_dir, "0.1.5")-- assert not manager.registry.is_installed(- "partial-install-failure-preset"- )- skill_file = (- project_dir- / ".github"- / "skills"- / "speckit-specify"- / "SKILL.md"- )- assert (- not skill_file.exists()- or "preset:partial-install-failure-preset"- not in original_read_text(skill_file, encoding="utf-8")- ), "rollback must not orphan a skill written before the later failure"-- def test_toggle_skills_to_command_empty_result_preserves_old_skill(- self, project_dir, temp_dir- ):- """A non-raising but empty command result must not delete the old skill.-- Mirror image of the empty-result command->skills case: deleting the- preset's own source file makes ``_register_commands`` return ``{}``- for copilot without raising, which must leave the old SKILL.md and- its tracking untouched (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "toggle-skill-empty-result-preset", "speckit.specify",- "Toggle empty-result test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:toggle-skill-empty-result-preset" in skill_file.read_text(), (- "sanity: skills mode should have written the SKILL.md mirror"- )-- # Remove the preset's own *installed* source file so- # _register_commands can find nothing to render β a real "missing- # source" case, not an exception β leaving registered_commands- # empty for copilot.- (manager.presets_dir / "toggle-skill-empty-result-preset" / "commands" / "speckit.specify.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- manager.register_enabled_presets_for_agent("copilot")-- assert "preset:toggle-skill-empty-result-preset" in skill_file.read_text(), (- "an empty (non-raising) command registration result must not "- "cause the old skills-mode artifact to be deleted/reverted "- "(#2948)"- )- metadata = manager.registry.get("toggle-skill-empty-result-preset")- assert "speckit-specify" in metadata["registered_skills"].get("copilot", []), (- "registered_skills must keep tracking copilot's still-live "- "skill file when nothing was actually replaced (#2948)"- )- # Note: a command file may still exist here β general command- # reconciliation independently restores the next-best (e.g. core)- # layer for the *command name*, regardless of this preset's own- # missing source. That's an orthogonal, existing behaviour; the- # invariant under test is specifically that the *skill* mirror and- # its tracking survive the empty registration result.-- def test_toggle_skills_to_command_partial_result_only_removes_replaced_skill(- self, project_dir, temp_dir- ):- """Only the skill whose command replacement actually landed is retired.-- Mirror image of the partial-result command->skills case: a- two-command preset where one command's source file goes missing- right before the toggle, so ``_register_commands`` genuinely- returns a partial result. The skill whose command was written- must be retired; the other must keep both its old SKILL.md and- its registry tracking, since no replacement for it landed (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")- self._create_skill(skills_dir, "speckit-plan")-- # A core template lets the retired skill restore to core content- # instead of being removed entirely (it has nothing else to fall- # back to), matching _unregister_skills's behaviour elsewhere.- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- preset_dir = self._create_multi_command_preset(- temp_dir, "toggle-skill-partial-result-preset",- ["speckit.specify", "speckit.plan"],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- specify_skill_file = skills_dir / "speckit-specify" / "SKILL.md"- plan_skill_file = skills_dir / "speckit-plan" / "SKILL.md"- assert "preset:toggle-skill-partial-result-preset" in specify_skill_file.read_text()- assert "preset:toggle-skill-partial-result-preset" in plan_skill_file.read_text()- metadata = manager.registry.get("toggle-skill-partial-result-preset")- assert set(metadata["registered_skills"].get("copilot", [])) == {- "speckit-specify", "speckit-plan",- }, "sanity: both skills should be tracked for copilot"-- # Remove only the plan command's *installed* source so its command- # replacement is silently skipped (missing source), while- # specify's succeeds.- (manager.presets_dir / "toggle-skill-partial-result-preset" / "commands" / "speckit.plan.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- manager.register_enabled_presets_for_agent("copilot")-- assert "preset:toggle-skill-partial-result-preset" not in specify_skill_file.read_text(), (- "the specify skill's old artifact must be retired/reverted "- "since its command replacement actually landed (#2948)"- )- assert "preset:toggle-skill-partial-result-preset" in plan_skill_file.read_text(), (- "the plan skill's old artifact must survive since its command "- "replacement never landed (missing source) (#2948)"- )- metadata = manager.registry.get("toggle-skill-partial-result-preset")- tracked_skills = metadata["registered_skills"].get("copilot", [])- assert "speckit-specify" not in tracked_skills, (- "specify must stop being tracked as a skill once its artifact "- "has been unregistered/reverted (#2948)"- )- assert "speckit-plan" in tracked_skills, (- "plan must keep being tracked as a skill since its old "- "artifact is still on disk (#2948)"- )- assert (copilot_commands_dir / "speckit.specify.agent.md").exists(), (- "sanity: specify's new command artifact should exist"- )-- def test_toggle_command_to_skills_retires_alias_group_when_primary_skill_lands(- self, project_dir, temp_dir- ):- """A command's aliases must be retired together with its primary- once the primary's skill replacement lands.-- ``CommandRegistrar.register_commands()`` tracks and returns- primary + alias names flattened together, but ``_register_skills()``- only ever renders/returns the *primary* command name's skill. The- alias's own name run through ``_skill_names_for_command()`` never- matches anything real, so without grouping by primary, the alias- command artifact and its tracking entry would survive forever even- after mutual exclusion is otherwise enforced for the primary (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_multi_command_preset_with_aliases(- temp_dir, "alias-group-success-preset",- [("speckit.specify", ["speckit.spec"])],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- primary_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- alias_cmd_file = copilot_commands_dir / "speckit.spec.agent.md"- assert primary_cmd_file.exists() and alias_cmd_file.exists(), (- "sanity: command mode should have written both the primary "- "and alias command files"- )- metadata = manager.registry.get("alias-group-success-preset")- assert set(metadata["registered_commands"].get("copilot", [])) == {- "speckit.specify", "speckit.spec",- }, "sanity: both primary and alias should be tracked for copilot"-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert not primary_cmd_file.exists(), (- "the primary's old command artifact must be retired once its "- "skill replacement lands (#2948)"- )- assert not alias_cmd_file.exists(), (- "the alias's old command artifact must be retired together "- "with its primary once the primary's skill replacement lands "- "(#2948)"- )- metadata = manager.registry.get("alias-group-success-preset")- registered_commands = metadata.get("registered_commands", {})- assert not registered_commands.get("copilot"), (- "neither the primary nor the alias should remain tracked as "- "commands once both artifacts are retired (#2948)"- )- skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"- assert skill_file.exists(), "sanity: the primary's skill should have been written"-- def test_toggle_command_to_skills_keeps_alias_group_when_primary_skill_missing(- self, project_dir, temp_dir- ):- """A command's aliases must survive together with its primary when- the primary's skill replacement never lands.-- Mirror image of the group-retirement case: deleting the preset's- own installed command source makes ``_register_skills`` genuinely- return nothing for ``speckit.specify``, so neither the primary nor- its alias have a real replacement β both old command artifacts and- their tracking must survive (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_multi_command_preset_with_aliases(- temp_dir, "alias-group-failure-preset",- [("speckit.specify", ["speckit.spec"])],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- primary_cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- alias_cmd_file = copilot_commands_dir / "speckit.spec.agent.md"- assert primary_cmd_file.exists() and alias_cmd_file.exists(), (- "sanity: command mode should have written both the primary "- "and alias command files"- )-- # Remove the installed source so _register_skills can find nothing- # to render for the primary β a real "missing source" case.- (manager.presets_dir / "alias-group-failure-preset" / "commands" / "speckit.specify.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert primary_cmd_file.exists(), (- "the primary's old command artifact must survive since its "- "skill replacement never landed (#2948)"- )- assert alias_cmd_file.exists(), (- "the alias's old command artifact must survive together with "- "its primary since neither has a real replacement (#2948)"- )- metadata = manager.registry.get("alias-group-failure-preset")- assert set(metadata["registered_commands"].get("copilot", [])) == {- "speckit.specify", "speckit.spec",- }, (- "both the primary and alias must keep being tracked since "- "nothing was actually replaced (#2948)"- )- skill_file = project_dir / ".github" / "skills" / "speckit-specify" / "SKILL.md"- assert not skill_file.exists(), (- "sanity: no skill should have been written when the source "- "was missing"- )-- def test_toggle_command_to_skills_partial_multi_group_only_retires_successful_group(- self, project_dir, temp_dir- ):- """With two independent alias groups, only the group whose primary- skill actually lands is retired; the other survives intact.-- A preset with two commands (``speckit.specify`` with alias- ``speckit.spec``, and ``speckit.plan`` with alias- ``speckit.plan-alt``) where only ``speckit.plan``'s installed- source goes missing: ``speckit.specify``'s group (primary + alias)- must be fully retired, while ``speckit.plan``'s entire group- (primary + alias) must survive together, since grouping is- per-primary, not per-individual-name (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_multi_command_preset_with_aliases(- temp_dir, "alias-group-partial-preset",- [- ("speckit.specify", ["speckit.spec"]),- ("speckit.plan", ["speckit.plan-alt"]),- ],- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- specify_cmd = copilot_commands_dir / "speckit.specify.agent.md"- spec_alias_cmd = copilot_commands_dir / "speckit.spec.agent.md"- plan_cmd = copilot_commands_dir / "speckit.plan.agent.md"- plan_alias_cmd = copilot_commands_dir / "speckit.plan-alt.agent.md"- assert all(- f.exists() for f in (specify_cmd, spec_alias_cmd, plan_cmd, plan_alias_cmd)- ), "sanity: command mode should have written all four command files"-- # Remove only plan's installed source so its group's skill- # replacement is silently skipped, while specify's group succeeds.- (manager.presets_dir / "alias-group-partial-preset" / "commands" / "speckit.plan.md").unlink()-- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- manager.register_enabled_presets_for_agent("copilot")-- assert not specify_cmd.exists() and not spec_alias_cmd.exists(), (- "specify's whole group (primary + alias) must be retired "- "since its skill replacement landed (#2948)"- )- assert plan_cmd.exists() and plan_alias_cmd.exists(), (- "plan's whole group (primary + alias) must survive together "- "since its skill replacement never landed (#2948)"- )- metadata = manager.registry.get("alias-group-partial-preset")- tracked_commands = set(metadata["registered_commands"].get("copilot", []))- assert tracked_commands == {"speckit.plan", "speckit.plan-alt"}, (- "only plan's group should remain tracked as commands; "- "specify's group must be fully untracked (#2948)"- )-- def test_rescaffold_toggle_skills_to_command_removes_stale_skill_file(- self, project_dir, temp_dir- ):- """Toggling the *same* agent from skills mode to command mode must- remove the stale skills-mode artifact, not just add the new one.-- Mirror image of the command-to-skills toggle: once ``ai_skills`` is- turned off for copilot (still the active agent), ``_get_skills_dir``- stops resolving a skills directory for it, so ``_register_skills``- becomes a no-op β but the ``SKILL.md`` written while skills mode was- on, and its ``registered_skills`` entry, were left behind even- though ``_register_commands`` went on to (re)write the ``.agent.md``- command file, again breaking mutual exclusion (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- # A core template lets the stale skill restore to core content- # (instead of being removed entirely, since it has nothing to fall- # back to), matching how `_unregister_skills` behaves elsewhere.- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- preset_dir = self._create_command_preset(- temp_dir, "toggle-skill-to-cmd-preset", "speckit.specify",- "Toggle test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:toggle-skill-to-cmd-preset" in skill_file.read_text(), (- "sanity: skills mode should have written the SKILL.md mirror"- )- metadata = manager.registry.get("toggle-skill-to-cmd-preset")- assert metadata["registered_skills"].get("copilot"), (- "sanity: the skills-mode write should be tracked for copilot"- )-- # Flip ai_skills off for the *same* active agent and rescaffold, as- # `integration upgrade copilot` would after the mode toggle.- self._write_init_options(project_dir, ai="copilot", ai_skills=False)- manager.register_enabled_presets_for_agent("copilot")-- restored_content = skill_file.read_text()- assert "preset:toggle-skill-to-cmd-preset" not in restored_content, (- "the stale skills-mode artifact must be reverted once copilot "- "has toggled to command mode for the same agent (#2948)"- )- assert "Core specify body" in restored_content, (- "sanity: the skill should fall back to core content, not just "- "lose the preset's override"- )- metadata = manager.registry.get("toggle-skill-to-cmd-preset")- assert not metadata["registered_skills"].get("copilot"), (- "registered_skills must stop tracking copilot once its "- "artifact has been unregistered/restored (#2948)"- )- cmd_file = copilot_commands_dir / "speckit.specify.agent.md"- assert cmd_file.exists(), (- "sanity: the new command-mode artifact should still be written"- )- assert "preset body" in cmd_file.read_text()-- def test_skill_switch_then_remove_restores_every_skill_agent_dir(- self, project_dir, temp_dir- ):- """Switching between two skill-mode agents before removing a preset- must restore both agents' directories, not just the currently- active one.-- ``registered_skills`` records exactly which agent directories the- preset wrote to (``{agent_name: [skill_name, ...]}``); switching to- codex and re-registering adds a "codex" entry alongside the- original "claude" entry, so removal restores both. Before the- provenance fix, ``_unregister_skills`` only restored the currently- active agent's skills directory; a preset used first under Claude- and later switched to Codex would have its Claude override left- behind permanently on removal (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- # Native skill agents only materialize a *brand-new* preset skill- # when their skills directory already exists (mirrors every other- # skill test in this class); pre-create both agents' directories so- # install and the later switch both find an existing skill to- # overwrite via _register_commands/_register_skills.- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "multi-skill-agent-preset", "speckit.specify",- "Multi skill agent test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:multi-skill-agent-preset" in claude_skill.read_text()-- # Switch the active agent to codex (a different skill-mode agent)- # and re-register enabled presets for it, mirroring what- # `integration use codex` does.- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")-- codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:multi-skill-agent-preset" in codex_skill.read_text(), (- "sanity: switching to codex should rescaffold the preset there"- )- assert "preset:multi-skill-agent-preset" in claude_skill.read_text(), (- "sanity: the previous agent's registration is preserved on switch"- )-- metadata = manager.registry.get("multi-skill-agent-preset")- registered_skills = metadata.get("registered_skills", {})- assert set(registered_skills) == {"claude", "codex"}, (- "registered_skills must record both agent directories this "- "preset actually wrote to (#2948)"- )-- assert manager.remove("multi-skill-agent-preset") is True-- for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):- assert skill_file.exists(), f"{label} skill file should still exist after removal"- content = skill_file.read_text()- assert "preset:multi-skill-agent-preset" not in content, (- f"{label}'s preset override must be restored on removal, "- "not orphaned permanently (#2948)"- )- assert "Core specify body" in content-- def test_native_skill_activation_recreates_deleted_skills_root(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- preset_dir = self._create_command_preset(- temp_dir,- "native-root-recovery-preset",- "speckit.specify",- "Native root recovery",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- codex_skills_dir = project_dir / ".agents" / "skills"- assert not codex_skills_dir.exists()- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")-- skill_file = codex_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:native-root-recovery-preset" in skill_file.read_text()- metadata = manager.registry.get("native-root-recovery-preset")- assert "speckit.specify" in metadata["registered_commands"]["codex"]-- def test_rescaffold_migrates_legacy_flat_list_registered_skills(- self, project_dir, temp_dir- ):- """Rescaffolding a preset with a legacy flat-list ``registered_skills``- entry must persist the migrated per-agent dict even when the- rescaffolded skill names are unchanged from before.-- ``_normalize_registered_skills`` converts a legacy flat ``List[str]``- (predating per-agent provenance) into ``{agent_name: [...]}`` in- memory, but the persistence check compared only the *normalized*- ``merged_skills`` against the *normalized* ``existing_skills`` β- both derived from the same raw legacy list. When the freshly- registered names are identical to what the legacy list already- held (the common case: nothing about the preset or skill actually- changed), that comparison is a no-op and ``registry.update()`` is- skipped, leaving the *raw* on-disk value as the un-migrated flat- list. A later switch to a different skill-mode agent and removal- then follows the legacy best-effort restore path (only the- currently active agent's directory) instead of the per-agent- provenance path, orphaning the first agent's override (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "legacy-skills-preset", "speckit.specify",- "Legacy skills test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Simulate a registry entry written by a pre-#2948 spec-kit version:- # registered_skills stored as a flat list with no per-agent- # provenance, rather than the dict shape install_from_directory- # writes today.- manager.registry.update(- "legacy-skills-preset", {"registered_skills": ["speckit-specify"]},- )- metadata = manager.registry.get("legacy-skills-preset")- assert isinstance(metadata["registered_skills"], list), (- "sanity: the injected legacy format is a flat list"- )-- # Rescaffold for the *same* active agent (claude) with no actual- # change to the registered skill names, mirroring `integration- # upgrade claude` re-running registration for the active- # integration.- manager.register_enabled_presets_for_agent("claude")-- metadata = manager.registry.get("legacy-skills-preset")- registered_skills = metadata.get("registered_skills")- assert isinstance(registered_skills, dict), (- "rescaffold must migrate a legacy flat-list registered_skills "- "entry to the per-agent dict format even when the "- "rescaffolded names are unchanged, or the raw registry stays "- "un-migrated and later removal loses per-agent provenance "- "(#2948)"- )- assert registered_skills.get("claude") == ["speckit-specify"]-- # Switch to a different skill-mode agent and rescaffold again β- # with the dict format now in place, both directories should be- # tracked and therefore restorable on removal.- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")-- metadata = manager.registry.get("legacy-skills-preset")- assert set(metadata.get("registered_skills", {})) == {"claude", "codex"}, (- "the migrated dict must keep recording every agent directory "- "the preset actually wrote to, exactly like a preset that was "- "always in dict format (#2948)"- )-- assert manager.remove("legacy-skills-preset") is True-- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"- for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):- assert skill_file.exists(), f"{label} skill file should still exist after removal"- content = skill_file.read_text()- assert "preset:legacy-skills-preset" not in content, (- f"{label}'s preset override must be restored on removal, "- "not orphaned because the registry stayed in legacy "- "flat-list format (#2948)"- )- assert "Core specify body" in content-- def test_rescaffold_legacy_flat_list_direct_switch_preserves_original_agent(- self, project_dir, temp_dir- ):- """A legacy flat-list ``registered_skills`` entry must not be- misattributed to the wrong agent when the *first* post-upgrade- operation is a direct switch to a different skill-mode agent.-- Blindly attributing every legacy flat-list name to ``agent_name`` β- the agent currently being (re)activated β loses the actual writer- whenever that first operation is ``integration use codex`` (or- ``switch``) run directly against a legacy Claude override, without- an intervening same-agent rescaffold for Claude first. The- migrated dict then only records ``{"codex": [...]}``, so a later- ``remove()`` restores Codex but permanently orphans the Claude- override that was never in the registry to begin with (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "legacy-direct-switch-preset", "speckit.specify",- "Legacy direct switch test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # install_from_directory wrote the preset's override to Claude's- # skill directory (the active agent at install time) β sanity-check- # that the marker is actually there before simulating the legacy- # registry format.- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:legacy-direct-switch-preset" in claude_skill.read_text(), (- "sanity: install should have written the override under claude"- )-- # Simulate a pre-#2948 registry: a flat list with no per-agent- # provenance, even though the file on disk was actually written- # under claude's directory.- manager.registry.update(- "legacy-direct-switch-preset",- {"registered_skills": ["speckit-specify"]},- )-- # Directly switch to codex β no intervening rescaffold for claude β- # mirroring `integration use codex` / `switch codex` run right after- # upgrading spec-kit versions.- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")-- metadata = manager.registry.get("legacy-direct-switch-preset")- registered_skills = metadata.get("registered_skills")- assert isinstance(registered_skills, dict)- assert set(registered_skills) == {"claude", "codex"}, (- "migrating a legacy flat-list entry on a direct switch must "- "infer the actual writer (claude) from the existing on-disk "- "SKILL.md provenance, not attribute every name to whichever "- "agent happens to be activated first after the upgrade "- "(#2948)"- )-- assert manager.remove("legacy-direct-switch-preset") is True-- codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"- for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):- assert skill_file.exists(), f"{label} skill file should still exist after removal"- content = skill_file.read_text()- assert "preset:legacy-direct-switch-preset" not in content, (- f"{label}'s preset override must be restored on removal, "- "not permanently orphaned by a misattributed legacy "- "migration (#2948)"- )- assert "Core specify body" in content-- def test_rescaffold_legacy_flat_list_infers_command_backed_skills_owner(- self, project_dir, temp_dir- ):- """Legacy provenance inference must also probe command-backed agents- that were running in skills mode, not only agents whose command- registrar config is statically ``/SKILL.md``-only.-- Copilot is command-backed (``extension: ".agent.md"``), but with- ``ai_skills`` enabled its preset overrides render as ``SKILL.md``- files under ``.github/skills`` exactly like a native skill-only- agent (claude, codex, ...). Before the fix,- ``_infer_legacy_skill_provenance`` only probed agents whose- registrar config has a static ``extension == "/SKILL.md"``, so a- real preset-owned ``.github/skills/.../SKILL.md`` written while- Copilot was the active, skills-mode agent was never found β the- legacy flat list was misattributed entirely to whichever agent the- first post-upgrade switch happened to activate, permanently- orphaning Copilot's override on later removal (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- copilot_skills_dir = project_dir / ".github" / "skills"- self._create_skill(copilot_skills_dir, "speckit-specify")- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "legacy-copilot-skills-preset", "speckit.specify",- "Legacy copilot skills test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- copilot_skill = copilot_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:legacy-copilot-skills-preset" in copilot_skill.read_text(), (- "sanity: install should have written the override under "- "copilot's skills directory while copilot was active in "- "skills mode"- )- # Sanity: no command-mode artifact was written either β copilot's- # command file and skills file are mutually exclusive.- assert not list((project_dir / ".github" / "agents").glob("*specify*")), (- "sanity: copilot in skills mode must not also write a command "- "file that could be falsely attributed instead"- )-- # Simulate a pre-#2948 registry: a flat list with no per-agent- # provenance, even though the file on disk was actually written- # under copilot's skills directory.- manager.registry.update(- "legacy-copilot-skills-preset",- {"registered_skills": ["speckit-specify"]},- )-- # Directly switch to claude β no intervening rescaffold for- # copilot β mirroring `integration use claude` run right after- # upgrading spec-kit versions.- self._write_init_options(project_dir, ai="claude", ai_skills=True)- manager.register_enabled_presets_for_agent("claude")-- metadata = manager.registry.get("legacy-copilot-skills-preset")- registered_skills = metadata.get("registered_skills")- assert isinstance(registered_skills, dict)- assert set(registered_skills) == {"copilot", "claude"}, (- "migrating a legacy flat-list entry on a direct switch must "- "infer the actual writer (copilot, running in skills mode) "- "even though copilot's registrar config is command-backed, "- "not just agents with a static /SKILL.md extension (#2948)"- )-- assert manager.remove("legacy-copilot-skills-preset") is True-- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- for skill_file, label in ((copilot_skill, "copilot"), (claude_skill, "claude")):- assert skill_file.exists(), f"{label} skill file should still exist after removal"- content = skill_file.read_text()- assert "preset:legacy-copilot-skills-preset" not in content, (- f"{label}'s preset override must be restored on removal, "- "not permanently orphaned by a legacy migration that "- "failed to probe command-backed skills-mode agents (#2948)"- )- assert "Core specify body" in content-- def test_infer_legacy_skill_provenance_does_not_falsely_attribute_command_mode_copilot(- self, project_dir, temp_dir- ):- """Broadening provenance inference to command-backed agents must not- falsely attribute ownership to an agent's directory that has no- preset-owned marker.-- Copilot stays in plain command mode throughout (no skills ever- rendered there), so ``.github/skills`` never receives this- preset's ``SKILL.md``. Probing copilot's skills directory anyway- (now that inference isn't restricted to static ``/SKILL.md``- agents) must find nothing there and must not invent a false- ``"copilot"`` entry (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- # Copilot has never been active; its command directory holds an- # unrelated file so the directory exists, but no skills directory- # or SKILL.md was ever written for it.- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)-- preset_dir = self._create_command_preset(- temp_dir, "no-false-attribution-preset", "speckit.specify",- "No false attribution test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- manager.registry.update(- "no-false-attribution-preset",- {"registered_skills": ["speckit-specify"]},- )-- # Rescaffold again for the same agent (claude) with unchanged- # names, triggering the legacy migration path.- manager.register_enabled_presets_for_agent("claude")-- metadata = manager.registry.get("no-false-attribution-preset")- registered_skills = metadata.get("registered_skills")- assert isinstance(registered_skills, dict)- assert set(registered_skills) == {"claude"}, (- "copilot must not appear in the migrated registry when it has "- "never actually rendered this preset's skill β probing its "- "directory for a marker match must not create a false "- "attribution (#2948)"- )- assert not (project_dir / ".github" / "skills").exists(), (- "no .github/skills directory should have been created as a "- "side effect of probing for provenance (#2948)"- )-- def test_infer_legacy_skill_provenance_skips_invalid_utf8(- self, project_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skill_dir = (- project_dir / ".claude" / "skills" / "speckit-specify"- )- skill_dir.mkdir(parents=True)- (skill_dir / "SKILL.md").write_bytes(b"\xff")-- manager = PresetManager(project_dir)-- assert manager._infer_legacy_skill_provenance(- ["speckit-specify"], "some-pack", "claude"- ) == {"claude": ["speckit-specify"]}-- def test_infer_legacy_skill_provenance_excludes_home_outputs(- self, project_dir, temp_dir, monkeypatch- ):- home = temp_dir / "home"- monkeypatch.setattr(Path, "home", lambda: home)- skill_dir = home / ".hermes" / "skills" / "speckit-specify"- skill_dir.mkdir(parents=True)- (skill_dir / "SKILL.md").write_text(- "---\n"- "metadata:\n"- " source: preset:some-pack\n"- "---\n\n"- "Other project\n",- encoding="utf-8",- )-- manager = PresetManager(project_dir)- inferred = manager._infer_legacy_skill_provenance(- ["speckit-specify"], "some-pack", "claude"- )-- assert inferred == {"claude": ["speckit-specify"]}- assert skill_dir.exists()-- def test_remove_infers_legacy_flat_list_provenance_without_prior_rescaffold(- self, project_dir, temp_dir- ):- """``preset remove`` on a legacy flat-list registry must restore- every previously active agent's directory, not just the currently- active one, even when it is the *very first* post-upgrade- operation (no intervening ``use``/``upgrade``/rescaffold).-- Pre-#2948 registries recorded a flat ``registered_skills`` list- because presets were rendered for every detected skill-mode agent- at once, not just the active one. Migrating that legacy format to- the per-agent dict form previously only happened as a side effect- of ``register_enabled_presets_for_agent`` (i.e. a rescaffold or- ``integration use``/``switch``). If the user's first action after- upgrading is instead directly running ``preset remove``, the- legacy branch of ``_unregister_skills`` restored only the- currently active agent's directory (via ``_get_skills_dir()``),- permanently leaving this preset's override in every other,- previously active agent's directory (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "remove-legacy-no-rescaffold-preset", "speckit.specify",- "Remove legacy no rescaffold test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:remove-legacy-no-rescaffold-preset" in claude_skill.read_text(), (- "sanity: install should have written the override under "- "claude's skill directory"- )- # Simulate the pre-#2948 "register for every detected agent"- # install behaviour by also placing the marker under codex's- # directory directly (mirroring the old, non-active-only- # rendering that predates this PR).- codex_skill = codex_skills_dir / "speckit-specify" / "SKILL.md"- codex_skill.write_text(claude_skill.read_text(), encoding="utf-8")-- # Simulate a pre-#2948 registry: a flat list with no per-agent- # provenance, even though both directories actually hold this- # preset's marker on disk.- manager.registry.update(- "remove-legacy-no-rescaffold-preset",- {"registered_skills": ["speckit-specify"]},- )-- # No intervening use/upgrade/rescaffold: remove() is the very- # first operation run after the legacy registry was written.- assert manager.remove("remove-legacy-no-rescaffold-preset") is True-- for skill_file, label in ((claude_skill, "claude"), (codex_skill, "codex")):- assert skill_file.exists(), f"{label} skill file should still exist after removal"- content = skill_file.read_text()- assert "preset:remove-legacy-no-rescaffold-preset" not in content, (- f"{label}'s preset override must be restored on removal "- "even with no prior rescaffold to migrate the legacy "- "flat-list format first β remove() must infer real "- "per-agent ownership from on-disk provenance itself "- "(#2948)"- )- assert "Core specify body" in content-- def test_symlinked_skills_dir_rejected_on_removal(self, project_dir, temp_dir):- """Removal must validate a recorded skill directory before touching it.-- If an agent's skills directory is replaced with a symlink escaping- the project root between install and removal, restoration must- refuse to write/rmtree through it rather than trusting the- recorded agent name blindly. The unsafe directory is skipped- best-effort; removal still succeeds and doesn't crash (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "symlink-guard-preset", "speckit.specify",- "Symlink guard test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- metadata = manager.registry.get("symlink-guard-preset")- assert "speckit-specify" in metadata.get("registered_skills", {}).get("claude", [])-- # Simulate the claude skills directory being replaced with a symlink- # that escapes the project root, containing an external- # "speckit-specify" directory that must not be touched.- outside_target = temp_dir / "outside-claude-skills"- outside_skill_dir = outside_target / "speckit-specify"- outside_skill_dir.mkdir(parents=True)- sentinel = outside_skill_dir / "SKILL.md"- sentinel.write_text("do-not-touch")- shutil.rmtree(claude_skills_dir)- claude_skills_dir.symlink_to(outside_target, target_is_directory=True)-- assert manager.remove("symlink-guard-preset") is True-- assert sentinel.read_text() == "do-not-touch", (- "removal must not follow a symlinked skills directory outside "- "the project root (#2948)"- )- assert outside_skill_dir.is_dir(), (- "the external directory must not be rmtree'd through a "- "symlinked skills path"- )- assert claude_skills_dir.is_symlink(), (- "the symlink itself should be left alone, not rmtree'd through"- )-- def test_preset_removal_does_not_touch_other_presets_skill_dir(- self, project_dir, temp_dir- ):- """Removing a preset must only touch directories it actually wrote to.-- Preset A is installed while Claude is active and preset B is- installed while Codex is active; both override the same command- name, so both materialize a ``speckit-specify`` skill, but in- *different* agent directories. Before the provenance fix, removing- B enumerated every existing skill-mode directory (including- Claude's) and restored/overwrote anything named ``speckit-specify``- found there, corrupting A's override even though B never touched- Claude's directory (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_skills_dir, "speckit-specify")-- preset_a_dir = self._create_command_preset(- temp_dir, "preset-a", "speckit.specify", "Preset A", "preset A body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_a_dir, "0.1.5")-- claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:preset-a" in claude_skill_file.read_text()-- # Switch to codex and install a second preset overriding the same- # command; codex's skills directory is entirely separate.- self._write_init_options(project_dir, ai="codex", ai_skills=True)- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")-- preset_b_dir = self._create_command_preset(- temp_dir, "preset-b", "speckit.specify", "Preset B", "preset B body",- )- manager.install_from_directory(preset_b_dir, "0.1.5")-- metadata_b = manager.registry.get("preset-b")- assert "claude" not in metadata_b.get("registered_skills", {}), (- "preset B never wrote to claude's skills directory and must "- "not record it as touched"- )-- assert manager.remove("preset-b") is True-- assert "preset:preset-a" in claude_skill_file.read_text(), (- "removing preset B must not disturb preset A's Claude override (#2948)"- )-- def test_remove_does_not_recreate_empty_skill_dir(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-orphan")- preset_dir = self._create_command_preset(- temp_dir,- "orphan-skill-preset",- "speckit.orphan",- "Orphan",- "Preset-only body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_dir = skills_dir / "speckit-orphan"- assert skill_dir.exists()- assert manager.remove("orphan-skill-preset") is True- assert not skill_dir.exists()-- def test_remove_preserves_non_owned_skill_during_reconciliation(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- self._create_skill(skills_dir, "speckit-specify")-- lower_dir = self._create_command_preset(- temp_dir,- "non-owned-lower-preset",- "speckit.specify",- "Lower",- "Lower preset body",- )- higher_dir = self._create_command_preset(- temp_dir,- "non-owned-higher-preset",- "speckit.specify",- "Higher",- "Higher preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(lower_dir, "0.1.5", priority=10)- manager.install_from_directory(higher_dir, "0.1.5", priority=1)-- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- skill_file.write_text(- "---\nname: speckit-specify\n---\n\nUser-owned body\n",- encoding="utf-8",- )-- assert manager.remove("non-owned-higher-preset") is True- assert skill_file.read_text(encoding="utf-8") == (- "---\nname: speckit-specify\n---\n\nUser-owned body\n"- )-- def test_shared_skills_dir_restored_once_using_active_agent(- self, project_dir, temp_dir- ):- """Removal must restore a physical skills directory shared by- multiple agents exactly once, using the active agent's renderer.-- Codex and Antigravity (agy) both resolve their skills directory to- ``.agents/skills``. Registering a preset under codex, switching to- agy, then switching back to codex records provenance for *both*- agent keys even though they share one physical directory. Before- the fix, ``_unregister_skills`` restored once per recorded agent- key rather than once per unique directory, so the directory was- written twice on removal with whichever agent was iterated *last*- silently winning β regardless of which agent is actually active- (#2948).- """- self._write_init_options(project_dir, ai="codex", ai_skills=True)- shared_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(shared_skills_dir, "speckit-specify")-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- preset_dir = self._create_command_preset(- temp_dir, "shared-dir-preset", "speckit.specify",- "Shared dir test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- # Switch to agy (shares .agents/skills with codex) and back to- # codex, mirroring `integration use agy` then `integration use- # codex`. Both agent keys end up recorded in registered_skills even- # though they refer to the same physical directory.- self._write_init_options(project_dir, ai="agy", ai_skills=True)- manager.register_enabled_presets_for_agent("agy")- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")-- metadata = manager.registry.get("shared-dir-preset")- registered_skills = metadata.get("registered_skills", {})- assert set(registered_skills) == {"codex", "agy"}, (- "both agent keys must be recorded even though they share one "- "physical directory (#2948)"- )-- from unittest.mock import patch-- # Exercise `_unregister_skills` directly (the method this fix- # changed) rather than the full `remove()` flow, which separately- # triggers post-removal reconciliation that may also touch the- # active agent's directory β an unrelated call this test isn't- # targeting.- with patch.object(- manager,- "_unregister_skills_in_dir",- wraps=manager._unregister_skills_in_dir,- ) as spy:- manager._unregister_skills(registered_skills, preset_dir)-- assert spy.call_count == 1, (- "a physical directory shared by multiple recorded agents must "- "be restored exactly once, not once per agent key (#2948)"- )- (_names, called_dir, called_agent), _kwargs = spy.call_args- assert called_dir == shared_skills_dir- assert called_agent == "codex", (- "the currently active agent must be used as the renderer when "- "it shares the restored directory, not whichever agent was "- "recorded last (#2948)"- )-- skill_file = shared_skills_dir / "speckit-specify" / "SKILL.md"- content = skill_file.read_text()- assert "preset:shared-dir-preset" not in content- assert "Core specify body" in content-- def test_remove_higher_priority_skills_only_preset_restores_lower_preset(- self, project_dir, temp_dir- ):- """Removing a skills-mode preset must reconcile against the surviving- stack, not fall back to core/extension content.-- Copilot in skills mode never populates ``registered_commands`` for- its overrides (``_register_commands``'s ``ai_skills`` guard skips- command-file registration entirely), so with two presets overriding- the same command, the removed preset's command name was never added- to ``removed_cmd_names`` and reconciliation was skipped outright.- ``_unregister_skills`` then restored straight to core/extension- content instead of resolving the lower-priority preset that should- now win (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)-- preset_a_dir = self._create_command_preset(- temp_dir, "skills-preset-a", "speckit.specify",- "Preset A", "preset A body",- )- preset_b_dir = self._create_command_preset(- temp_dir, "skills-preset-b", "speckit.specify",- "Preset B", "preset B body",- )-- manager = PresetManager(project_dir)- # Lower priority number = higher precedence.- manager.install_from_directory(preset_a_dir, "0.1.5", priority=5)- manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)-- skills_dir = project_dir / ".github" / "skills"- skill_file = skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:skills-preset-a" in skill_file.read_text(), (- "sanity: the higher-precedence preset should win initially"- )-- assert manager.remove("skills-preset-a") is True-- content = skill_file.read_text()- assert "preset:skills-preset-b" in content, (- "removing the higher-precedence skills-mode preset must "- "restore the surviving lower-precedence preset's override, "- "not fall back to core/extension content (#2948)"- )- assert "preset:skills-preset-a" not in content-- def test_composed_none_unregister_respects_active_agent(- self, project_dir, temp_dir- ):- """Unregistering a stale composed command must only touch the- active agent's directory, not every configured non-skill agent.-- When a wrap preset's base layer is removed, ``resolve_content`` can- no longer find a replace layer to compose onto and returns- ``None``, triggering the "composed is None" branch of- ``_reconcile_composed_commands``. Before the fix, that- unregistration mapping covered every configured non-skill agent- regardless of ``only_agent``, deleting historical artifacts from- integrations that were never active for this preset (#2948).- """- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_commands_dir = project_dir / ".gemini" / "commands"- gemini_commands_dir.mkdir(parents=True)-- # A made-up command name with no bundled/core equivalent, so the- # *only* base layer is the "compose-base" preset installed below β- # once it's removed, no base remains for the wrap preset to compose- # onto.- cmd_name = "speckit.fake-compose-test"- base_dir = self._create_command_preset(- temp_dir, "compose-base", cmd_name, "Base", "base body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(base_dir, "0.1.5", priority=10)-- wrap_dir = temp_dir / "compose-wrap"- wrap_dir.mkdir()- (wrap_dir / "commands").mkdir()- (wrap_dir / "commands" / f"{cmd_name}.md").write_text(- "---\ndescription: Wrap\nstrategy: wrap\n---\n\n"- "wrap start\n{CORE_TEMPLATE}\nwrap end\n"- )- manifest_data = {- "schema_version": "1.0",- "preset": {- "id": "compose-wrap",- "name": "compose-wrap",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": cmd_name,- "file": f"commands/{cmd_name}.md",- "strategy": "wrap",- }- ]- },- }- with open(wrap_dir / "preset.yml", "w") as f:- yaml.dump(manifest_data, f)- manager.install_from_directory(wrap_dir, "0.1.5", priority=5)-- cmd_file = gemini_commands_dir / f"{cmd_name}.toml"- assert cmd_file.exists(), (- "sanity: the composed command should register for the active agent"- )-- # Simulate a pre-existing artifact for an inactive agent, predating- # this preset entirely β active-only unregistration must never- # touch it.- opencode_dir = project_dir / ".opencode" / "commands"- opencode_dir.mkdir(parents=True, exist_ok=True)- opencode_stale_file = opencode_dir / f"{cmd_name}.md"- opencode_stale_file.write_text("stale opencode content\n")-- assert manager.remove("compose-base") is True-- assert not cmd_file.exists(), (- "sanity: the active agent's now-uncomposable command file must "- "be unregistered"- )- assert opencode_stale_file.read_text() == "stale opencode content\n", (- "unregistering a stale composed command must not touch an "- "inactive agent's directory (#2948)"- )-- def test_remove_reconciles_command_for_every_historical_agent(- self, project_dir, temp_dir- ):- """Removing a preset must reconcile every historical agent its- ``registered_commands`` actually targeted, not only the currently- active one.-- Preset B (lower precedence, survives) is installed while gemini is- active, then preset A (higher precedence) overrides the same- command while gemini is still active. Switching the active- integration to opencode and rescaffolding re-registers both- presets under opencode too, so preset A's ``registered_commands``- now spans two agents: gemini (now inactive) and opencode (active).- Removing A deletes its command file from *both* directories via- ``_unregister_commands``, but active-only reconciliation used to- recreate the surviving preset B's content only for the active- agent (opencode), leaving gemini's directory with a stale/missing- file (#2948).- """- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- preset_b_dir = self._create_command_preset(- temp_dir, "hist-preset-b", "speckit.specify",- "Preset B", "preset B body",- )- preset_a_dir = self._create_command_preset(- temp_dir, "hist-preset-a", "speckit.specify",- "Preset A", "preset A body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)- manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)-- gemini_cmd_files = list(gemini_dir.glob("*specify*"))- assert gemini_cmd_files, "sanity: gemini should have the command file"- assert "preset A body" in gemini_cmd_files[0].read_text(), (- "sanity: preset A (higher precedence) should win initially"- )-- # Switch the active integration to opencode and rescaffold, mirroring- # `integration use opencode`. This merges opencode into both- # presets' registered_commands alongside the pre-existing gemini- # entry recorded while gemini was active.- self._write_init_options(project_dir, ai="opencode", ai_skills=False)- opencode_dir = project_dir / ".opencode" / "commands"- opencode_dir.mkdir(parents=True, exist_ok=True)- manager.register_enabled_presets_for_agent("opencode")-- metadata_a = manager.registry.get("hist-preset-a")- assert set(metadata_a.get("registered_commands", {})) == {"gemini", "opencode"}, (- "sanity: preset A's registered_commands must span both the "- "historical (gemini) and currently active (opencode) agents"- )-- assert manager.remove("hist-preset-a") is True-- gemini_cmd_files = list(gemini_dir.glob("*specify*"))- opencode_cmd_files = list(opencode_dir.glob("*specify*"))- assert gemini_cmd_files, "gemini's command file must still exist after removal"- assert opencode_cmd_files, "opencode's command file must still exist after removal"- assert "preset B body" in gemini_cmd_files[0].read_text(), (- "removing the higher-precedence preset must restore the "- "surviving preset's content in the historical (inactive) "- "agent's directory too, not only the active agent's (#2948)"- )- assert "preset B body" in opencode_cmd_files[0].read_text(), (- "the surviving preset's content must also be restored for the "- "currently active agent"- )-- def test_remove_reconciliation_tracks_new_historical_agent_for_survivor(- self, project_dir, temp_dir- ):- """Historical-agent reconciliation writes must be recorded in the- surviving preset's own ``registered_commands``, not just written- to disk and forgotten.-- Preset A is installed while gemini is active, then survives to be- active under opencode too (so A's ``registered_commands`` spans- both gemini and opencode). Preset B is installed *only* while- opencode is active β B's ``registered_commands`` is- ``{"opencode": [...]}`` and never mentions gemini. Removing A- triggers reconciliation that writes B's content into gemini's- directory (an agent B never wrote to before) via ``extra_agents``,- but if that write isn't merged back into B's own- ``registered_commands``, B's registry entry still only says- ``{"opencode": [...]}`` even though B's content now lives in- gemini's directory too. A later ``remove('b')`` then only cleans- up opencode, leaving the gemini file β reconciled there entirely- by side effect of removing A β as a permanent orphan with no- preset tracking it (#2948).- """- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- preset_a_dir = self._create_command_preset(- temp_dir, "orphan-preset-a", "speckit.specify",- "Preset A", "preset A body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)-- self._write_init_options(project_dir, ai="opencode", ai_skills=False)- opencode_dir = project_dir / ".opencode" / "commands"- opencode_dir.mkdir(parents=True, exist_ok=True)- manager.register_enabled_presets_for_agent("opencode")-- metadata_a = manager.registry.get("orphan-preset-a")- assert set(metadata_a.get("registered_commands", {})) == {"gemini", "opencode"}, (- "sanity: preset A must be tracked under both agents"- )-- # Preset B is installed only now, while opencode is the sole- # active agent β it never writes to or tracks gemini.- preset_b_dir = self._create_command_preset(- temp_dir, "orphan-preset-b", "speckit.specify",- "Preset B", "preset B body",- )- manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)-- metadata_b = manager.registry.get("orphan-preset-b")- assert set(metadata_b.get("registered_commands", {})) == {"opencode"}, (- "sanity: preset B must only be tracked for opencode before "- "preset A is removed"- )-- assert manager.remove("orphan-preset-a") is True-- # B is now written into gemini's directory as a side effect of- # reconciling A's removal, via the historical-agent extra_agents- # pass.- gemini_cmd_files = list(gemini_dir.glob("*specify*"))- assert gemini_cmd_files, "sanity: gemini's directory must have B's restored content"- assert "preset B body" in gemini_cmd_files[0].read_text(encoding="utf-8")-- metadata_b = manager.registry.get("orphan-preset-b")- assert set(metadata_b.get("registered_commands", {})) == {"gemini", "opencode"}, (- "preset B's own registered_commands must be updated to "- "include gemini once reconciliation actually writes content "- "there on its behalf β otherwise B's registry entry silently "- "lies about which directories it owns (#2948)"- )-- assert manager.remove("orphan-preset-b") is True-- # No preset is installed any more, so gemini's file must have been- # reconciled down to the core bundled template (or removed- # entirely) β but it must NOT still contain B's stale content,- # which would mean B's write there was never tracked for cleanup.- remaining_gemini_files = list(gemini_dir.glob("*specify*"))- for f in remaining_gemini_files:- assert "preset B body" not in f.read_text(encoding="utf-8"), (- "removing preset B must clean up gemini's directory too, "- "since B's registered_commands was updated to include it "- "β otherwise B's stale content is orphaned there forever "- "with no preset left to track or clean it up (#2948)"- )-- def test_extension_reconciliation_tracks_new_historical_agent(- self, project_dir- ):- from specify_cli.extensions import ExtensionRegistry-- self._write_init_options(project_dir, ai="opencode", ai_skills=False)- (project_dir / ".opencode" / "commands").mkdir(parents=True)- (project_dir / ".gemini" / "commands").mkdir(parents=True)-- ext_dir = project_dir / ".specify" / "extensions" / "tracked-ext"- (ext_dir / "commands").mkdir(parents=True)- (ext_dir / "commands" / "tracked.md").write_text(- "---\ndescription: tracked\n---\n\nExtension body\n",- encoding="utf-8",- )- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: tracked-ext\n name: Tracked\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " commands:\n"- " - name: speckit.tracked\n"- " file: commands/tracked.md\n"- " description: Tracked command\n",- encoding="utf-8",- )- ExtensionRegistry(ext_dir.parent).add(- "tracked-ext",- {- "version": "1.0.0",- "source": "dev",- "enabled": True,- "registered_commands": {- "opencode": ["speckit.tracked-ext.tracked"]- },- },- )-- manager = PresetManager(project_dir)- manager._reconcile_composed_commands(- ["speckit.tracked-ext.tracked"], extra_agents={"gemini"}- )-- assert list((project_dir / ".gemini" / "commands").glob("*tracked*"))- metadata = ExtensionRegistry(ext_dir.parent).get("tracked-ext")- assert set(metadata["registered_commands"]) == {"gemini", "opencode"}-- def test_remove_reconciles_skill_for_every_historical_agent(- self, project_dir, temp_dir- ):- """Removing a preset must reconcile every historical skills- directory its ``registered_skills`` actually targeted, not only- the currently active one.-- Preset B (survives) is installed while claude is active, then- preset A (higher precedence) overrides the same command while- claude is still active. Switching to codex and rescaffolding- records codex too, so preset A's ``registered_skills`` spans both- claude (now inactive) and codex (active) directories. Removing A- restores both directories to core/extension via- ``_unregister_skills``, but ``_reconcile_skills`` used to only- resolve/apply the surviving winner for the currently active- skills directory, leaving claude's directory reverted to- core/extension content instead of preset B's override (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"-- # A core template fallback is required so unregistering the- # top-priority preset's SKILL.md restores core content rather than- # deleting the skill directory outright when no preset remains to- # apply on top of it (mirrors the pre-existing skills-reconciliation- # fixtures elsewhere in this file).- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- preset_b_dir = self._create_command_preset(- temp_dir, "hist-skill-preset-b", "speckit.specify",- "Preset B", "preset B body",- )- preset_a_dir = self._create_command_preset(- temp_dir, "hist-skill-preset-a", "speckit.specify",- "Preset A", "preset A body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)- manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)-- claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:hist-skill-preset-a" in claude_skill_file.read_text(), (- "sanity: preset A (higher precedence) should win initially"- )-- # Switch the active integration to codex (a distinct skills- # directory) and rescaffold, mirroring `integration use codex`.- self._write_init_options(project_dir, ai="codex", ai_skills=True)- codex_skills_dir = project_dir / ".agents" / "skills"- manager.register_enabled_presets_for_agent("codex")-- metadata_a = manager.registry.get("hist-skill-preset-a")- assert set(metadata_a.get("registered_skills", {})) == {"claude", "codex"}, (- "sanity: preset A's registered_skills must span both the "- "historical (claude) and currently active (codex) agents"- )-- assert manager.remove("hist-skill-preset-a") is True-- codex_skill_file = codex_skills_dir / "speckit-specify" / "SKILL.md"- assert claude_skill_file.exists(), "claude's skill file must still exist after removal"- assert codex_skill_file.exists(), "codex's skill file must still exist after removal"- assert "preset:hist-skill-preset-b" in claude_skill_file.read_text(), (- "removing the higher-precedence preset must restore the "- "surviving preset's override in the historical (inactive) "- "agent's directory too, not only the active agent's (#2948)"- )- assert "preset:hist-skill-preset-b" in codex_skill_file.read_text(), (- "the surviving preset's override must also be restored for "- "the currently active agent"- )-- def test_skill_reconciliation_preserves_per_directory_names(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_dir = project_dir / ".claude" / "skills"- self._create_skill(claude_dir, "speckit-alpha")- alpha_dir = self._create_command_preset(- temp_dir, "partial-alpha", "speckit.alpha",- "Alpha", "alpha body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(alpha_dir, "0.1.5")-- self._write_init_options(project_dir, ai="codex", ai_skills=True)- codex_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_dir, "speckit-beta")- beta_dir = self._create_command_preset(- temp_dir, "partial-beta", "speckit.beta",- "Beta", "beta body",- )- manager.install_from_directory(beta_dir, "0.1.5")-- affected = manager._unregister_skills(- {- "claude": ["speckit-alpha"],- "codex": ["speckit-beta"],- },- manager.presets_dir / "partial-alpha",- )- manager._reconcile_skills(- ["speckit.alpha", "speckit.beta"],- extra_skills_dirs=affected,- )-- assert (claude_dir / "speckit-alpha" / "SKILL.md").exists()- assert (codex_dir / "speckit-beta" / "SKILL.md").exists()- assert not (claude_dir / "speckit-beta").exists()- assert not (codex_dir / "speckit-alpha").exists()-- def test_skill_reconciliation_rejects_unsafe_managed_names(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- skills_dir.mkdir(parents=True)- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )- absolute_escape = temp_dir / "absolute-escape"- traversal_escape = project_dir / ".claude" / "traversal-escape"-- manager = PresetManager(project_dir)- manager._reconcile_skills(- ["speckit.specify"],- extra_skills_dirs={- skills_dir: (- "claude",- [str(absolute_escape), "../traversal-escape"],- )- },- )-- assert not absolute_escape.exists()- assert not traversal_escape.exists()-- def test_remove_reconciliation_tracks_new_historical_skill_agent_for_survivor(- self, project_dir, temp_dir- ):- """Historical-agent skill reconciliation writes must be recorded in- the surviving preset's own ``registered_skills``, mirroring- ``test_remove_reconciliation_tracks_new_historical_agent_for_survivor``- for the command side.-- Preset A is installed while claude is active, then survives to be- active under codex too (so A's ``registered_skills`` spans both- claude and codex). Preset B is installed *only* while codex is- active β B's ``registered_skills`` is ``{"codex": [...]}`` and- never mentions claude. Removing A triggers reconciliation that- renders B's SKILL.md into claude's directory (an agent B never- wrote to before) via ``extra_skills_dirs``, but if that write- isn't merged back into B's own ``registered_skills``, a later- ``remove('b')`` only cleans up codex, leaving claude's SKILL.md β- rendered there entirely by side effect of removing A β untracked- by any preset (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- # Pre-create the skill so _register_commands/_register_skills find- # an existing skill to overwrite (mirrors every other skill test- # in this class β native skill agents only overwrite already- # existing skill directories, they don't materialize brand-new- # ones outside of active-agent creation).- self._create_skill(claude_skills_dir, "speckit-specify")-- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- preset_a_dir = self._create_command_preset(- temp_dir, "orphan-skill-preset-a", "speckit.specify",- "Preset A", "preset A body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_a_dir, "0.1.5", priority=1)-- self._write_init_options(project_dir, ai="codex", ai_skills=True)- codex_skills_dir = project_dir / ".agents" / "skills"- self._create_skill(codex_skills_dir, "speckit-specify")- manager.register_enabled_presets_for_agent("codex")-- metadata_a = manager.registry.get("orphan-skill-preset-a")- assert set(metadata_a.get("registered_skills", {})) == {"claude", "codex"}, (- "sanity: preset A must be tracked under both agents"- )-- # Preset B is installed only now, while codex is the sole active- # agent β it never writes to or tracks claude.- preset_b_dir = self._create_command_preset(- temp_dir, "orphan-skill-preset-b", "speckit.specify",- "Preset B", "preset B body",- )- manager.install_from_directory(preset_b_dir, "0.1.5", priority=10)-- metadata_b = manager.registry.get("orphan-skill-preset-b")- assert set(metadata_b.get("registered_skills", {})) == {"codex"}, (- "sanity: preset B must only be tracked for codex before "- "preset A is removed"- )-- assert manager.remove("orphan-skill-preset-a") is True-- claude_skill_file = claude_skills_dir / "speckit-specify" / "SKILL.md"- assert claude_skill_file.exists(), (- "sanity: claude's skill file must have been restored by "- "reconciliation"- )- assert "preset:orphan-skill-preset-b" in claude_skill_file.read_text(), (- "sanity: claude's SKILL.md must reflect preset B's content "- "after preset A is removed"- )-- metadata_b = manager.registry.get("orphan-skill-preset-b")- assert set(metadata_b.get("registered_skills", {})) == {"claude", "codex"}, (- "preset B's own registered_skills must be updated to include "- "claude once reconciliation actually renders content there "- "on its behalf β otherwise B's registry entry silently lies "- "about which directories it owns (#2948)"- )-- assert manager.remove("orphan-skill-preset-b") is True-- # No preset is installed any more, so claude's SKILL.md must have- # been reconciled down to the core bundled template (or removed- # entirely) β but it must NOT still contain B's stale content,- # which would mean B's write there was never tracked for cleanup.- if claude_skill_file.exists():- assert "preset:orphan-skill-preset-b" not in claude_skill_file.read_text(), (- "removing preset B must clean up claude's directory too, "- "since B's registered_skills was updated to include it β "- "otherwise B's stale content is orphaned there forever "- "with no preset left to track or clean it up (#2948)"- )-- def test_symlinked_skill_subdir_rejected_on_restore(self, project_dir, temp_dir):- """Restore must validate each per-skill subdirectory, not just its parent.-- ``_safe_skills_dir_for_agent`` only validates the parent skills- directory (e.g. ``.claude/skills``); a symlink planted one level- deeper at the individual skill's own subdirectory (e.g.- ``.claude/skills/speckit-specify``) has a perfectly safe parent and- would otherwise slip past that check, since ``is_dir()`` follows- symlinks. Restoration must refuse to write/rmtree through it (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- claude_skills_dir.mkdir(parents=True)-- outside_target = temp_dir / "outside-skill-subdir"- outside_target.mkdir()- sentinel = outside_target / "SKILL.md"- sentinel.write_text("do-not-touch")- (claude_skills_dir / "speckit-specify").symlink_to(- outside_target, target_is_directory=True- )-- manager = PresetManager(project_dir)- manager._unregister_skills_in_dir(- ["speckit-specify"], claude_skills_dir, "claude"- )-- assert sentinel.read_text() == "do-not-touch", (- "restoration must not follow a symlinked skill subdirectory "- "to write/delete outside the project (#2948)"- )- assert (claude_skills_dir / "speckit-specify").is_symlink(), (- "the symlink itself should be left alone, not rmtree'd through"- )-- def test_symlinked_skill_subdir_rejected_on_write(self, project_dir, temp_dir):- """Registration must validate each per-skill subdirectory before writing.-- A symlink planted at an individual skill's own subdirectory (safe- parent, unsafe leaf) would otherwise pass the existing- ``skill_subdir.exists() and not skill_subdir.is_dir()`` guard- (``is_dir()`` follows symlinks) and have ``SKILL.md`` written- through it to an arbitrary location (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- copilot_commands_dir = project_dir / ".github" / "agents"- copilot_commands_dir.mkdir(parents=True)- skills_dir = project_dir / ".github" / "skills"- skills_dir.mkdir(parents=True)-- outside_target = temp_dir / "outside-skill-write-target"- outside_target.mkdir()- (skills_dir / "speckit-specify").symlink_to(- outside_target, target_is_directory=True- )-- preset_dir = self._create_command_preset(- temp_dir, "symlink-write-preset", "speckit.specify",- "Symlink write test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- assert not (outside_target / "SKILL.md").exists(), (- "registration must not follow a symlinked skill subdirectory "- "to write outside the project (#2948)"- )- assert (skills_dir / "speckit-specify").is_symlink(), (- "the symlink itself should be left alone"- )-- def test_symlinked_skill_file_rejected_on_write(self, project_dir, temp_dir):- """Registration must not follow a symlinked SKILL.md destination."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- (project_dir / ".github" / "agents").mkdir(parents=True)- skill_dir = (- project_dir / ".github" / "skills" / "speckit-specify"- )- skill_dir.mkdir(parents=True)- outside_file = temp_dir / "outside-registration.md"- outside_file.write_text("do-not-touch", encoding="utf-8")- (skill_dir / "SKILL.md").symlink_to(outside_file)-- preset_dir = self._create_command_preset(- temp_dir,- "symlink-file-write-preset",- "speckit.specify",- "Symlink file write",- "preset body",- )- manager = PresetManager(project_dir)- with pytest.raises(ValueError):- manager.install_from_directory(preset_dir, "0.1.5")-- assert outside_file.read_text(encoding="utf-8") == "do-not-touch"- assert (skill_dir / "SKILL.md").is_symlink()-- def test_symlinked_skill_file_rejected_on_restore(- self, project_dir, temp_dir- ):- """Restoration must not follow a symlinked SKILL.md destination."""- self._write_init_options(project_dir, ai="claude", ai_skills=True)- core_commands = project_dir / ".specify" / "templates" / "commands"- (core_commands / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )- skill_dir = (- project_dir / ".claude" / "skills" / "speckit-specify"- )- skill_dir.mkdir(parents=True)- outside_file = temp_dir / "outside-restoration.md"- outside_file.write_text("do-not-touch", encoding="utf-8")- (skill_dir / "SKILL.md").symlink_to(outside_file)-- manager = PresetManager(project_dir)- with pytest.raises(ValueError):- manager._unregister_skills_in_dir(- ["speckit-specify"], skill_dir.parent, "claude"- )-- assert outside_file.read_text(encoding="utf-8") == "do-not-touch"- assert (skill_dir / "SKILL.md").is_symlink()-- def test_symlinked_skill_file_rejected_on_override_reconcile(- self, project_dir, temp_dir- ):- """Project-override reconciliation must not follow SKILL.md symlinks."""- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- skill_dir = (- project_dir / ".github" / "skills" / "speckit-specify"- )- skill_dir.mkdir(parents=True)- outside_file = temp_dir / "outside-reconciliation.md"- outside_file.write_text("do-not-touch", encoding="utf-8")- (skill_dir / "SKILL.md").symlink_to(outside_file)-- preset_dir = self._create_command_preset(- temp_dir,- "symlink-override-preset",- "speckit.specify",- "Preset",- "Preset body",- )- manager = PresetManager(project_dir)- manager.registry.add(- "symlink-override-preset",- {- "version": "1.0.0",- "source": "local",- "enabled": True,- "priority": 10,- "registered_commands": {},- "registered_skills": {- "copilot": ["speckit-specify"]- },- },- )- installed_dir = (- manager.presets_dir / "symlink-override-preset"- )- shutil.copytree(preset_dir, installed_dir)- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Override\n---\n\nOverride body\n",- encoding="utf-8",- )-- manager._reconcile_skills(["speckit.specify"])-- assert outside_file.read_text(encoding="utf-8") == "do-not-touch"- assert (skill_dir / "SKILL.md").is_symlink()-- def test_is_safe_registry_skill_name_rejects_unsafe_values(self, project_dir):- """Unit-test the centralized registry skill-name boundary guard.-- ``registered_skills`` entries are persisted registry data, not- manifest-derived, so every preset cleanup/provenance loop that- joins one onto a directory must first reject: non-strings, empty- strings, absolute paths, multi-component paths (containing ``/``),- and the literal traversal components ``"."``/``".."`` β the last- of which is *not* caught by a naive ``is_absolute() or- len(parts) != 1`` check alone, since ``Path("..").parts`` is a- single-element tuple (#2948).- """- manager = PresetManager(project_dir)- is_safe = manager._is_safe_registry_skill_name-- assert is_safe("speckit-specify") is True- assert is_safe("") is False- assert is_safe(None) is False- assert is_safe(123) is False- assert is_safe(["speckit-specify"]) is False- assert is_safe(".") is False- assert is_safe("..") is False- assert is_safe("/etc/passwd") is False- assert is_safe(str(project_dir / "important-data")) is False- assert is_safe("foo/bar") is False- assert is_safe("foo/..") is False- assert is_safe("../foo") is False-- def test_unregister_skills_rejects_unknown_agent_provenance(- self, project_dir- ):- """Unknown registry agent keys must not fall back to shared skills."""- shared_skills_dir = project_dir / ".agents" / "skills"- skill_dir = self._create_skill(- shared_skills_dir, "speckit-specify", "user-owned content"- )- core_commands = project_dir / ".specify" / "templates" / "commands"- (core_commands / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )-- manager = PresetManager(project_dir)- manager._unregister_skills(- {"unknown": ["speckit-specify"]}, project_dir- )-- assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (- "---\nname: speckit-specify\n---\n\nuser-owned content\n"- )-- def test_unregister_legacy_fallback_skips_non_owned_skill(- self, project_dir- ):- """Legacy fallback provenance must not overwrite a user-owned skill."""- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- skill_dir = self._create_skill(- skills_dir, "speckit-specify", "user-owned content"- )- core_commands = project_dir / ".specify" / "templates" / "commands"- (core_commands / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )-- manager = PresetManager(project_dir)- manager._unregister_skills(- ["speckit-specify"], "removed-preset"- )-- assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (- "---\nname: speckit-specify\n---\n\nuser-owned content\n"- )-- def test_unregister_skills_in_dir_unreadable_core_template_skips(- self, project_dir- ):- """An undecodable core template must not crash `preset remove`.-- Every other failure in the restore loop β an unsafe registry name,- a missing skill subdirectory, a foreign owner β skips the skill- with ``continue``. The core-template read was outside that- boundary, so one non-UTF-8 project-owned override in- ``.specify/templates/commands/`` raised a raw ``UnicodeDecodeError``- straight out of ``PresetManager.remove()``, which has no handler- for it. Sibling reads of the very same directory are already- guarded (``_substitute_core_template``, the provenance reads in- ``_infer_legacy_skill_provenance``).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- skill_dir = self._create_skill(- skills_dir, "speckit-specify", "installed content"- )- core_commands = project_dir / ".specify" / "templates" / "commands"- core_commands.mkdir(parents=True, exist_ok=True)- (core_commands / "specify.md").write_bytes(- b"---\ndescription: \xff\xfe not utf-8\n---\n\nCore body\n"- )-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="speckit-specify"):- mutated = manager._unregister_skills_in_dir(- ["speckit-specify"], skills_dir, "claude"- )-- assert mutated == [], (- "a skill whose restore source could not be read was not "- "restored, so it must not be reported as mutated"- )- assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (- "---\nname: speckit-specify\n---\n\ninstalled content\n"- ), (- "an unreadable core template must leave the skill untouched β "- "falling through to the rmtree branch would delete it exactly "- "when its replacement cannot be generated"- )-- def test_unregister_skills_in_dir_unreadable_core_template_oserror_skips(- self, project_dir, monkeypatch- ):- """The same boundary must cover ``OSError`` (e.g. permission denied).-- Mocked rather than chmod-based so the case also holds under- privileged CI, where permission bits are not enforced.- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- skill_dir = self._create_skill(- skills_dir, "speckit-specify", "installed content"- )- core_commands = project_dir / ".specify" / "templates" / "commands"- core_commands.mkdir(parents=True, exist_ok=True)- core_template = core_commands / "specify.md"- core_template.write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )-- original_read_text = Path.read_text-- def failing_read_text(self_path, *args, **kwargs):- if self_path == core_template:- raise PermissionError(13, "Permission denied")- return original_read_text(self_path, *args, **kwargs)-- monkeypatch.setattr(Path, "read_text", failing_read_text)-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="speckit-specify"):- mutated = manager._unregister_skills_in_dir(- ["speckit-specify"], skills_dir, "claude"- )-- monkeypatch.undo()-- assert mutated == []- assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (- "---\nname: speckit-specify\n---\n\ninstalled content\n"- )-- def test_unregister_skills_in_dir_unreadable_extension_source_skips(- self, project_dir- ):- """The extension-restore arm needs the same boundary as the core arm.-- The two restore reads are independent branches β a skill backed by an- installed extension never reaches the core-template read β so this- half of the guard can regress on its own. An undecodable extension- command file must warn, leave the skill byte-for-byte intact, and stay- out of ``mutated_names``.- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- skills_dir = project_dir / ".claude" / "skills"- skill_dir = self._create_skill(- skills_dir, "speckit-fakeext-cmd", "installed content"- )-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "commands" / "cmd.md").write_bytes(- b"---\ndescription: \xff\xfe not utf-8\n---\n\nExtension body\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- manager = PresetManager(project_dir)- with pytest.warns(UserWarning, match="speckit-fakeext-cmd"):- mutated = manager._unregister_skills_in_dir(- ["speckit-fakeext-cmd"], skills_dir, "claude"- )-- assert mutated == [], (- "a skill whose extension restore source could not be read was "- "not restored, so it must not be reported as mutated"- )- assert (skill_dir / "SKILL.md").read_text(encoding="utf-8") == (- "---\nname: speckit-fakeext-cmd\n---\n\ninstalled content\n"- ), (- "an unreadable extension source must leave the skill untouched β "- "falling through to the rmtree branch would delete it exactly "- "when its replacement cannot be generated"- )-- def test_unregister_skills_in_dir_rejects_absolute_registry_name(- self, project_dir- ):- """A corrupted ``registered_skills`` entry with an absolute path must not escape.-- ``Path`` join with an absolute right-hand operand discards the- left side entirely (``skills_dir / "/abs/path"`` == ``"/abs/path"``),- so an absolute in-project path stored in the registry would bypass- ``skills_dir`` altogether if not rejected before the join (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- claude_skills_dir.mkdir(parents=True)-- precious_dir = project_dir / "important-data"- precious_dir.mkdir()- precious_file = precious_dir / "SKILL.md"- precious_file.write_text("precious-absolute-target-marker")-- manager = PresetManager(project_dir)- manager._unregister_skills_in_dir(- [str(precious_dir)], claude_skills_dir, "claude"- )-- assert precious_dir.is_dir(), (- "an absolute registry entry must not let cleanup escape "- "skills_dir to an unrelated project directory (#2948)"- )- assert precious_file.read_text() == "precious-absolute-target-marker"-- def test_infer_legacy_skill_provenance_rejects_absolute_registry_name(- self, project_dir- ):- """Legacy provenance inference must reject an absolute registry name.-- ``_infer_legacy_skill_provenance`` receives its ``skill_names``- directly from a legacy flat-list ``registered_skills`` value β- registry data, not manifest-derived β and joins each name onto a- candidate agent's resolved skills directory the same way- ``_unregister_skills_in_dir`` does. An absolute in-project name- discards the candidate directory entirely (Python's ``/`` operator- drops the left side for an absolute right side), so it can read- an unrelated project directory's ``SKILL.md`` and, if its- frontmatter happens to carry a matching preset source marker,- falsely attribute an unrelated directory as this preset's own- skill override under whichever agent is being probed (#2948).- """- self._write_init_options(project_dir, ai="claude", ai_skills=True)- claude_skills_dir = project_dir / ".claude" / "skills"- claude_skills_dir.mkdir(parents=True)-- precious_dir = project_dir / "important-data"- precious_dir.mkdir()- (precious_dir / "SKILL.md").write_text(- "---\n"- "metadata:\n"- " source: preset:some-pack\n"- "---\n\n"- "# Unrelated directory, not a real preset skill\n"- )-- manager = PresetManager(project_dir)- inferred = manager._infer_legacy_skill_provenance(- [str(precious_dir)], "some-pack", "claude"- )-- for names in inferred.values():- assert str(precious_dir) not in names, (- "an absolute registry entry must not be falsely attributed "- "as preset-owned provenance by probing outside the "- "intended skills subtree (#2948)"- )-- def test_copilot_skills_registration_restored_after_process_restart(- self, project_dir, temp_dir- ):- """Copilot skills-mode registrations must restore even when the- transient ``_skills_mode`` integration attribute has been reset,- simulating a fresh CLI process.-- ``_skills_mode`` is set during ``setup()`` and is never persisted;- after switching the active agent and running ``preset remove`` in- a brand-new process, a naive "is this integration currently in- skills mode" check would be False even though Copilot's- ``.github/skills`` directory holds a live override this preset- wrote. Restoration must rely on the persisted per-agent provenance- recorded at write time, not on runtime integration state (#2948).- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )- copilot_skills_dir = project_dir / ".github" / "skills"- self._create_skill(copilot_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "copilot-fresh-process-preset", "speckit.specify",- "Copilot fresh process test", "preset body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_file = copilot_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:copilot-fresh-process-preset" in skill_file.read_text()-- metadata = manager.registry.get("copilot-fresh-process-preset")- assert "copilot" in metadata.get("registered_skills", {})-- # Switch the active agent away from copilot, then simulate a fresh- # CLI process (a brand-new PresetManager, so any transient- # `_skills_mode` state set during a prior setup() call is gone)- # removing the preset.- self._write_init_options(project_dir, ai="claude", ai_skills=True)- fresh_manager = PresetManager(project_dir)-- assert fresh_manager.remove("copilot-fresh-process-preset") is True-- assert "preset:copilot-fresh-process-preset" not in skill_file.read_text(), (- "removal must restore copilot's .github/skills override even "- "when copilot's transient skills-mode state isn't set in this "- "process (#2948)"- )- assert "Core specify body" in skill_file.read_text()-- def test_unregister_agent_artifacts_scoped_to_target_agent_only(- self, project_dir, temp_dir- ):- """``unregister_agent_artifacts`` must remove only the target- agent's own tracked command/skill artifacts.-- Used by ``integration switch`` when deactivating the previous- integration for a not-yet-installed target (#2948): without this,- a preset's command override -- including a custom preset command --- and skill mirror rendered for the old agent remain orphaned once a- different integration becomes active. Another agent's own- registrations (files and registry tracking) must survive- untouched, and no priority-stack reconciliation should run as a- side effect.- """- self._write_init_options(project_dir, ai="auggie", ai_skills=False)- # Registration only writes to an agent's directory once it's- # "detected" on disk (mirroring a real `integration install`- # having already created it), so pre-create both agents'- # directories before installing the preset.- (project_dir / ".augment" / "commands").mkdir(parents=True)- (project_dir / ".opencode" / "commands").mkdir(parents=True)- preset_dir = self._create_command_preset(- temp_dir, "switch-cleanup-preset", "speckit.specify",- "Custom preset command", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- auggie_cmd = project_dir / ".augment" / "commands" / "speckit.specify.md"- assert auggie_cmd.exists(), "sanity: preset command registered for auggie"-- # Simulate a later `integration use opencode` rescaffold that also- # registered the preset for opencode, while auggie's own- # registration (from before the switch) is still present in the- # registry.- self._write_init_options(project_dir, ai="opencode", ai_skills=False)- manager.register_enabled_presets_for_agent("opencode")-- opencode_cmd = project_dir / ".opencode" / "commands" / "speckit.specify.md"- assert opencode_cmd.exists(), "sanity: preset command registered for opencode"-- metadata = manager.registry.get("switch-cleanup-preset")- registered_commands = metadata.get("registered_commands", {})- assert "auggie" in registered_commands and "opencode" in registered_commands-- manager.unregister_agent_artifacts("auggie")-- assert not auggie_cmd.exists(), (- "auggie's own preset command must be removed when switching "- "away from auggie to a not-yet-installed integration (#2948)"- )- assert opencode_cmd.exists(), (- "opencode's preset command must survive unregistering auggie's "- "artifacts -- cleanup must stay scoped to the target agent"- )-- metadata = manager.registry.get("switch-cleanup-preset")- registered_commands = metadata.get("registered_commands", {})- assert "auggie" not in registered_commands, (- "auggie's tracking must be dropped after unregistering its artifacts"- )- assert "opencode" in registered_commands, (- "opencode's tracking must be preserved untouched"- )-- def test_unregister_agent_artifacts_deletes_marker_owned_skill(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify\n---\n\nCore body\n",- encoding="utf-8",- )- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")- preset_dir = self._create_command_preset(- temp_dir,- "deactivated-skill-preset",- "speckit.specify",- "Deactivation cleanup",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- skill_dir = skills_dir / "speckit-specify"- assert "preset:deactivated-skill-preset" in (- skill_dir / "SKILL.md"- ).read_text()-- manager.unregister_agent_artifacts("copilot")-- assert not skill_dir.exists()-- def test_unregister_agent_artifacts_deletes_reconciled_override_skill(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- skills_dir = project_dir / ".github" / "skills"- self._create_skill(skills_dir, "speckit-specify")- preset_dir = self._create_command_preset(- temp_dir,- "deactivated-override-preset",- "speckit.specify",- "Deactivation override cleanup",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"- )- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.specify.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",- )- (- manager.presets_dir- / "deactivated-override-preset"- / "commands"- / "speckit.specify.md"- ).unlink()- manager.register_enabled_presets_for_agent("copilot")-- skill_dir = skills_dir / "speckit-specify"- assert "override:speckit.specify" in (- skill_dir / "SKILL.md"- ).read_text(encoding="utf-8")-- manager.unregister_agent_artifacts("copilot")-- assert not skill_dir.exists()- metadata = manager.registry.get("deactivated-override-preset")- assert "copilot" not in metadata.get("registered_skills", {})-- def test_unregister_native_agent_persists_skills_metadata_pop(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="agy", ai_skills=True)- (project_dir / ".agents" / "skills").mkdir(parents=True)- preset_dir = self._create_command_preset(- temp_dir,- "native-metadata-cleanup-preset",- "speckit.shared-cleanup",- "Shared cleanup",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- metadata = manager.registry.get("native-metadata-cleanup-preset")- assert "agy" in metadata.get("registered_commands", {})- manager.registry.update(- "native-metadata-cleanup-preset",- {"registered_skills": {"agy": ["speckit-shared-cleanup"]}},- )-- manager.unregister_agent_artifacts("agy")-- metadata = manager.registry.get("native-metadata-cleanup-preset")- assert "agy" not in metadata.get("registered_commands", {})- assert "agy" not in metadata.get("registered_skills", {})-- def test_unregister_native_agent_preserves_shared_output_owner(- self, project_dir, temp_dir- ):- self._write_init_options(project_dir, ai="agy", ai_skills=True)- (project_dir / ".agents" / "skills").mkdir(parents=True)- preset_dir = self._create_command_preset(- temp_dir,- "shared-native-output-preset",- "speckit.shared-owner",- "Shared owner",- "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- self._write_init_options(project_dir, ai="codex", ai_skills=True)- manager.register_enabled_presets_for_agent("codex")- skill_file = (- project_dir- / ".agents"- / "skills"- / "speckit-shared-owner"- / "SKILL.md"- )- assert skill_file.exists()- metadata = manager.registry.get("shared-native-output-preset")- registered_commands = metadata.get("registered_commands", {})- assert "agy" in registered_commands and "codex" in registered_commands-- manager.unregister_agent_artifacts("agy")-- assert skill_file.exists(), (- "shared SKILL.md must survive while codex still owns the same "- "physical output"- )- metadata = manager.registry.get("shared-native-output-preset")- registered_commands = metadata.get("registered_commands", {})- assert "agy" not in registered_commands- assert "codex" in registered_commands-- def test_unregister_agent_artifacts_migrates_legacy_skill_list_scoped(- self, project_dir, temp_dir- ):- """Unregistering an agent's artifacts from a legacy flat-list- ``registered_skills`` entry must infer real per-agent ownership- before removing anything, so only the target agent's own share is- cleaned up and any other agent's still-live mirror survives,- rather than either guessing every name belongs to the target agent- or dropping all tracking wholesale (#2948).-- Uses Copilot (command-backed, rendering skills via ``ai_skills``)- as the agent being switched away from, and Claude (a native- SKILL.md agent) as the separate, still-live owner β mirroring the- established legacy-provenance test pattern used elsewhere for- this exact registry shape.- """- self._write_init_options(project_dir, ai="copilot", ai_skills=True)- core_cmds = project_dir / ".specify" / "templates" / "commands"- core_cmds.mkdir(parents=True, exist_ok=True)- (core_cmds / "specify.md").write_text(- "---\ndescription: Core specify command\n---\n\nCore specify body\n",- encoding="utf-8",- )-- copilot_skills_dir = project_dir / ".github" / "skills"- claude_skills_dir = project_dir / ".claude" / "skills"- self._create_skill(copilot_skills_dir, "speckit-specify")- self._create_skill(claude_skills_dir, "speckit-specify")-- preset_dir = self._create_command_preset(- temp_dir, "switch-legacy-skill-preset", "speckit.specify",- "Legacy skill switch test", "preset body",- )- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- copilot_skill = copilot_skills_dir / "speckit-specify" / "SKILL.md"- assert "preset:switch-legacy-skill-preset" in copilot_skill.read_text(), (- "sanity: install wrote the override under copilot"- )-- # A separate activation under claude (before provenance tracking- # existed) also left a live, marker-verified mirror there.- claude_skill = claude_skills_dir / "speckit-specify" / "SKILL.md"- claude_skill.write_text(- "---\nname: speckit-specify\nmetadata:\n source: preset:switch-legacy-skill-preset\n"- "---\n\npreset body\n",- encoding="utf-8",- )-- # Simulate a pre-#2948 registry: a flat list with no per-agent- # provenance for either writer.- manager.registry.update(- "switch-legacy-skill-preset",- {"registered_skills": ["speckit-specify"]},- )-- manager.unregister_agent_artifacts("copilot")-- assert not copilot_skill.parent.exists(), (- "copilot's marker-owned preset skill must be deleted when "- "switching away from copilot"- )-- assert "preset:switch-legacy-skill-preset" in claude_skill.read_text(), (- "claude's own, separately-written mirror must survive "- "unregistering copilot's artifacts -- legacy-list inference "- "must not misattribute or drop claude's real ownership (#2948)"- )-- metadata = manager.registry.get("switch-legacy-skill-preset")- registered_skills = metadata.get("registered_skills")- assert isinstance(registered_skills, dict), (- "legacy flat-list value must migrate to per-agent form"- )- assert "copilot" not in registered_skills- assert "claude" in registered_skills and "speckit-specify" in registered_skills["claude"], (- "claude's real ownership must be preserved in the migrated tracking"- )-- def test_short_and_namespaced_commands_scaffold_consistently(- self, project_dir, temp_dir- ):- """A preset's ``speckit.<cmd>`` and ``speckit.<ns>.<cmd>`` commands must- scaffold identically in command mode, with no installed extension.-- Regression: the 3-part (``speckit.<ns>.<cmd>``) form was silently- dropped by a name-shape guard whenever ``.specify/extensions/<ns>/``- was absent, even though the preset ships the command body itself. The- 2-part form always scaffolded. Both are self-contained and must behave- the same (#4076).- """- self._write_init_options(project_dir, ai="gemini", ai_skills=False)- gemini_commands_dir = project_dir / ".gemini" / "commands"- gemini_commands_dir.mkdir(parents=True)-- short_preset = self._create_command_preset(- temp_dir, "short-cmd", "speckit.newcmd", "Short", "short body",- )- ns_preset = self._create_command_preset(- temp_dir, "ns-cmd", "speckit.fakeext.newcmd", "Namespaced", "ns body",- )-- manager = PresetManager(project_dir)- manager.install_from_directory(short_preset, "0.1.5")- manager.install_from_directory(ns_preset, "0.1.5")-- short_file = gemini_commands_dir / "speckit.newcmd.toml"- ns_file = gemini_commands_dir / "speckit.fakeext.newcmd.toml"- assert short_file.exists(), "2-part command should scaffold"- assert ns_file.exists(), (- "3-part namespaced command must scaffold too, even without the "- "matching extension installed"- )- assert manager.registry.get("short-cmd")["registered_commands"] != {}- assert manager.registry.get("ns-cmd")["registered_commands"] != {}-----class TestPresetPriorityBackwardsCompatibility:- """Test backwards compatibility for presets installed before priority feature."""-- def test_legacy_preset_without_priority_field(self, temp_dir):- """Presets installed before priority feature should default to 10."""- presets_dir = temp_dir / ".specify" / "presets"- presets_dir.mkdir(parents=True)-- # Simulate legacy registry entry without priority field- registry = PresetRegistry(presets_dir)- registry.data["presets"]["legacy-pack"] = {- "version": "1.0.0",- "source": "local",- "enabled": True,- "installed_at": "2025-01-01T00:00:00Z",- # No "priority" field - simulates pre-feature preset- }- registry._save()-- # Reload registry- registry2 = PresetRegistry(presets_dir)-- # list_by_priority should use default of 10- result = registry2.list_by_priority()- assert len(result) == 1- assert result[0][0] == "legacy-pack"- # Priority defaults to 10 and is normalized in returned metadata- assert result[0][1]["priority"] == 10-- def test_legacy_preset_in_list_installed(self, project_dir, pack_dir):- """list_installed returns priority=10 for legacy presets without priority field."""- manager = PresetManager(project_dir)-- # Install preset normally- manager.install_from_directory(pack_dir, "0.1.5")-- # Manually remove priority to simulate legacy preset- pack_data = manager.registry.data["presets"]["test-pack"]- del pack_data["priority"]- manager.registry._save()-- # list_installed should still return priority=10- installed = manager.list_installed()- assert len(installed) == 1- assert installed[0]["priority"] == 10-- def test_mixed_legacy_and_new_presets_ordering(self, temp_dir):- """Legacy presets (no priority) sort with default=10 among prioritized presets."""- presets_dir = temp_dir / ".specify" / "presets"- presets_dir.mkdir(parents=True)-- registry = PresetRegistry(presets_dir)-- # Add preset with explicit priority=5- registry.add("pack-with-priority", {"version": "1.0.0", "priority": 5})-- # Add legacy preset without priority (manually)- registry.data["presets"]["legacy-pack"] = {- "version": "1.0.0",- "source": "local",- "enabled": True,- # No priority field- }-- # Add another preset with priority=15- registry.add("low-priority-pack", {"version": "1.0.0", "priority": 15})- registry._save()-- # Reload and check ordering- registry2 = PresetRegistry(presets_dir)- sorted_presets = registry2.list_by_priority()-- # Should be: pack-with-priority (5), legacy-pack (default 10), low-priority-pack (15)- assert [p[0] for p in sorted_presets] == [- "pack-with-priority",- "legacy-pack",- "low-priority-pack",- ]---class TestPresetEnableDisable:- """Test preset enable/disable CLI commands."""---------- def test_disabled_preset_excluded_from_resolution(self, project_dir, pack_dir):- """Test that disabled presets are excluded from template resolution."""- # Install preset with a template- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- # Create a template in the preset directory- preset_template = project_dir / ".specify" / "presets" / "test-pack" / "templates" / "test-template.md"- preset_template.parent.mkdir(parents=True, exist_ok=True)- preset_template.write_text("# Template from test-pack")-- resolver = PresetResolver(project_dir)-- # Template should be found when enabled- result = resolver.resolve("test-template", "template")- assert result is not None- assert "test-pack" in str(result)-- # Disable the preset- manager.registry.update("test-pack", {"enabled": False})-- # Template should NOT be found when disabled- resolver2 = PresetResolver(project_dir)- result2 = resolver2.resolve("test-template", "template")- assert result2 is None-----# ===== Lean Preset Tests =====---LEAN_PRESET_DIR = Path(__file__).parent.parent / "presets" / "lean"-CORE_CONSTITUTION_COMMAND = (- Path(__file__).parent.parent / "templates" / "commands" / "constitution.md"-)--LEAN_COMMAND_NAMES = [- "speckit.specify",- "speckit.plan",- "speckit.tasks",- "speckit.implement",- "speckit.constitution",-]--- "command_path",- [- CORE_CONSTITUTION_COMMAND,- LEAN_PRESET_DIR / "commands" / "speckit.constitution.md",- ],- ids=["core", "lean"],-)-def test_constitution_commands_guard_against_non_governance_work(command_path):- """Constitution commands defer non-governance work instead of executing it."""- content = command_path.read_text()- lower_content = content.lower()- normalized_content = " ".join(lower_content.split())-- assert "## Scope Guard" in content- assert "**MUST NOT**" in content- assert "Classify every part" in content- assert "application source files" in content- assert "non-governance intent" in content- assert "`Next Actions`" in content- assert "__SPECKIT_COMMAND_SPECIFY__" in content- assert "omit" in lower_content- assert "do not invoke it" in normalized_content or "without invoking it" in normalized_content---def test_core_constitution_command_resolves_template_at_runtime():- """The core command must consume the composed scaffold on every invocation."""- content = CORE_CONSTITUTION_COMMAND.read_text()-- assert "resolve-template.sh constitution-template --json" in content- assert "resolve-template.ps1 constitution-template -Json" in content- assert "resolve_template.py constitution-template --json" in content- assert "parse `TEMPLATE_CONTENT` as the active template" in content- assert "do not continue with only one contributing" in content- assert "Do not write back to any versioned template layer" in content---def test_core_checklist_command_resolves_template_at_runtime():- """The checklist command must consume the composed scaffold."""- content = (CORE_CONSTITUTION_COMMAND.parent / "checklist.md").read_text(- encoding="utf-8"- )-- assert "--template checklist-template" in content- assert "TEMPLATE_CONTENT" in content- assert "Use TEMPLATE_CONTENT as the structural template" in content---class TestLeanPreset:- """Tests for the lean preset that ships with the repo."""-- def test_lean_preset_exists(self):- """Verify the lean preset directory and manifest exist."""- assert LEAN_PRESET_DIR.exists()- assert (LEAN_PRESET_DIR / "preset.yml").exists()-- def test_lean_manifest_valid(self):- """Verify the lean preset manifest is valid."""- manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")- assert manifest.id == "lean"- assert manifest.name == "Lean Workflow"- assert manifest.version == "1.0.0"- assert len(manifest.templates) == 5 # 5 commands-- def test_lean_provides_core_workflow_commands(self):- """Verify the lean preset provides overrides for core workflow commands."""- manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")- provided_names = {t["name"] for t in manifest.templates}- for name in LEAN_COMMAND_NAMES:- assert name in provided_names, f"Lean preset missing command: {name}"-- def test_lean_command_files_exist(self):- """Verify that all declared command files actually exist on disk."""- manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")- for tmpl in manifest.templates:- tmpl_path = LEAN_PRESET_DIR / tmpl["file"]- assert tmpl_path.exists(), f"Missing command file: {tmpl['file']}"-- def test_lean_commands_have_no_scripts(self):- """Verify lean commands have no scripts in frontmatter."""- from specify_cli.agents import CommandRegistrar-- for name in LEAN_COMMAND_NAMES:- cmd_path = LEAN_PRESET_DIR / "commands" / f"speckit.{name.split('.')[-1]}.md"- content = cmd_path.read_text()- frontmatter, _ = CommandRegistrar.parse_frontmatter(content)- assert "scripts" not in frontmatter, f"{name} should not have scripts in frontmatter"-- def test_lean_commands_have_no_hooks(self):- """Verify lean commands do not contain extension hook boilerplate."""- for name in LEAN_COMMAND_NAMES:- cmd_path = LEAN_PRESET_DIR / "commands" / f"speckit.{name.split('.')[-1]}.md"- content = cmd_path.read_text()- assert "hooks." not in content, f"{name} should not reference extension hooks"- assert "extensions.yml" not in content, f"{name} should not reference extensions.yml"-- def test_install_lean_preset(self, project_dir):- """Test installing the lean preset from its directory."""- manager = PresetManager(project_dir)- manifest = manager.install_from_directory(LEAN_PRESET_DIR, "0.6.0")- assert manifest.id == "lean"- assert manager.registry.is_installed("lean")-- def test_lean_overrides_commands(self, project_dir):- """Test that lean preset overrides are resolved correctly."""- manager = PresetManager(project_dir)- manager.install_from_directory(LEAN_PRESET_DIR, "0.6.0")-- resolver = PresetResolver(project_dir)- for name in LEAN_COMMAND_NAMES:- result = resolver.resolve(name, template_type="command")- assert result is not None, f"Lean override for {name} not resolved"---# ===== Bundled Preset Locator Tests =====---class TestBundledPresetLocator:- """Tests for _locate_bundled_preset discovery function."""-- def test_locate_bundled_lean_preset(self):- """_locate_bundled_preset finds the lean preset."""- from specify_cli import _locate_bundled_preset-- path = _locate_bundled_preset("lean")- assert path is not None- assert (path / "preset.yml").is_file()-- def test_locate_bundled_preset_not_found(self):- """_locate_bundled_preset returns None for nonexistent preset."""- from specify_cli import _locate_bundled_preset-- path = _locate_bundled_preset("nonexistent-preset")- assert path is None-- def test_locate_bundled_preset_rejects_invalid_id(self):- """_locate_bundled_preset rejects IDs with invalid characters."""- from specify_cli import _locate_bundled_preset-- assert _locate_bundled_preset("../escape") is None- assert _locate_bundled_preset("UPPERCASE") is None- assert _locate_bundled_preset("has spaces") is None-------------- def test_bundled_preset_in_catalog(self):- """Verify the lean preset is listed in catalog.json with bundled marker."""- catalog_path = Path(__file__).parent.parent / "presets" / "catalog.json"- catalog = json.loads(catalog_path.read_text())- assert "lean" in catalog["presets"]- assert catalog["presets"]["lean"]["bundled"] is True- assert "download_url" not in catalog["presets"]["lean"]-- def test_bundled_preset_download_raises_error(self, project_dir):- """download_pack raises PresetError for bundled presets without download_url."""- catalog = PresetCatalog(project_dir)-- catalog_data = {- "test-bundled": {- "name": "Test Bundled",- "version": "1.0.0",- "bundled": True,- }- }- from unittest.mock import patch- with patch.object(catalog, "_get_merged_packs", return_value=catalog_data):- with pytest.raises(PresetError, match="bundled with spec-kit"):- catalog.download_pack("test-bundled")------class TestWrapStrategy:- """Tests for strategy: wrap preset command substitution."""-- def test_substitute_core_template_replaces_placeholder(self, project_dir):- """Core template body replaces {CORE_TEMPLATE} in preset command body."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- # Set up a core command template- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\n---\n\n# Core Specify\n\nDo the thing.\n"- )-- registrar = CommandRegistrar()- body = "## Pre-Logic\n\nBefore stuff.\n\n{CORE_TEMPLATE}\n\n## Post-Logic\n\nAfter stuff.\n"- result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)-- assert "{CORE_TEMPLATE}" not in result- assert "# Core Specify" in result- assert "## Pre-Logic" in result- assert "## Post-Logic" in result- assert core_fm.get("description") == "core"-- def test_substitute_core_template_no_op_when_placeholder_absent(self, project_dir):- """Returns body unchanged when {CORE_TEMPLATE} is not present."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text("---\ndescription: core\n---\n\nCore body.\n")-- registrar = CommandRegistrar()- body = "## No placeholder here.\n"- result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)- assert result == body- assert core_fm == {}+ @pytest.mark.parametrize(+ "value",+ ["εε-γγγΈγ§γ―γ", "cafΓ©-rΓ©sumΓ©", "Ξ©mega-Ξelta", "π-launch"],+ )+ def test_save_load_round_trip_preserves_non_ascii(self, project_dir, value):+ """Non-ASCII values round-trip via explicit UTF-8 encoding.- def test_substitute_core_template_no_op_when_core_missing(self, project_dir):- """Returns body unchanged when core template file does not exist."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar+ ``Path.write_text`` / ``Path.read_text`` default to the system+ locale codec on Windows (cp1252 / gb2312 / cp932). Without+ ``encoding="utf-8"`` pinned on both ends, a project name like+ ``cafΓ©`` written on a UTF-8 host becomes garbled or unreadable on+ a cp1252 host (and vice versa). Pin UTF-8 explicitly so init+ options round-trip across machines and CI.- registrar = CommandRegistrar()- body = "Pre.\n\n{CORE_TEMPLATE}\n\nPost.\n"- result, core_fm = _substitute_core_template(body, "nonexistent", project_dir, registrar)- assert result == body- assert "{CORE_TEMPLATE}" in result- assert core_fm == {}-- def test_substitute_core_template_unreadable_core_treated_as_missing(- self, project_dir- ):- """An undecodable core template must not crash substitution.-- The wrap-strategy callers (``CommandRegistrar.register_pack`` and- ``_register_commands``) skip an unreadable preset source with a- warning, but the core template read inside- ``_substitute_core_template`` had no boundary, so one corrupted- project-owned override in ``.specify/templates/commands/`` crashed- the whole registration with a raw ``UnicodeDecodeError``. An- unreadable core is treated like a missing one.+ Note: this test only meaningfully exercises the encoding pin+ because ``save_init_options`` now writes JSON with+ ``ensure_ascii=False`` β otherwise ``json.dumps`` would output+ ASCII-only ``\\uXXXX`` escapes and the encoding pin would be a+ no-op for any value here. ``test_save_writes_real_utf8_bytes``+ below asserts that contract directly."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_bytes(b"\xff\xfe not utf-8")-- registrar = CommandRegistrar()- body = "Pre.\n\n{CORE_TEMPLATE}\n\nPost.\n"- with pytest.warns(UserWarning, match="Ignoring core template"):- result, core_fm = _substitute_core_template(- body, "specify", project_dir, registrar- )- assert result == body- assert core_fm == {}-- def test_register_commands_substitutes_core_template_for_wrap_strategy(self, project_dir):- """register_commands substitutes {CORE_TEMPLATE} when strategy: wrap."""- from specify_cli.agents import CommandRegistrar-- # Set up core command template- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\n---\n\n# Core Specify\n\nCore body here.\n"- )-- # Create a preset command dir with a wrap-strategy command- cmd_dir = project_dir / "preset" / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: wrap test\nstrategy: wrap\n---\n\n"- "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"- )-- commands = [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}]- registrar = CommandRegistrar()-- # Use a generic agent that writes markdown to commands/- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)-- # Patch AGENT_CONFIGS to use a simple markdown agent pointing at our dir- import copy- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown",- "args": "$ARGUMENTS",- "extension": ".md",- "strip_frontmatter_keys": [],- }- try:- registrar.register_commands(- "test-agent", commands, "test-preset",- project_dir / "preset", project_dir- )- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- assert "{CORE_TEMPLATE}" not in written- assert "# Core Specify" in written- assert "## Pre" in written- assert "## Post" in written-- def test_end_to_end_wrap_via_self_test_preset(self, project_dir):- """Installing self-test preset with a wrap command substitutes {CORE_TEMPLATE}."""- from specify_cli.presets import PresetManager-- # Install a core template that wrap-test will wrap around- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "wrap-test.md").write_text(- "---\ndescription: core wrap-test\n---\n\n# Core Wrap-Test Body\n"- )-- # Set up skills dir (simulating --integration claude)- skills_dir = project_dir / ".claude" / "skills"- skills_dir.mkdir(parents=True, exist_ok=True)- skill_subdir = skills_dir / "speckit-wrap-test"- skill_subdir.mkdir()- (skill_subdir / "SKILL.md").write_text("---\nname: speckit-wrap-test\n---\n\nold content\n")-- # Write init-options so _register_skills finds the claude skills dir- import json- (project_dir / ".specify" / "init-options.json").write_text(- json.dumps({"ai": "claude", "ai_skills": True})- )-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- written = (skill_subdir / "SKILL.md").read_text()- assert "{CORE_TEMPLATE}" not in written- assert "# Core Wrap-Test Body" in written- assert "preset:self-test wrap-pre" in written- assert "preset:self-test wrap-post" in written-- def test_substitute_core_template_returns_core_scripts(self, project_dir):- """core_frontmatter in the returned tuple includes scripts/agent_scripts."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: run.sh\nagent_scripts:\n sh: agent-run.sh\n---\n\n# Body\n"- )-- registrar = CommandRegistrar()- body = "## Wrapper\n\n{CORE_TEMPLATE}\n"- result, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)-- assert "# Body" in result- assert core_fm.get("scripts") == {"sh": "run.sh"}- assert core_fm.get("agent_scripts") == {"sh": "agent-run.sh"}-- def test_register_skills_inherits_scripts_from_core_when_preset_omits_them(self, project_dir):- """_register_skills merges scripts/agent_scripts from core when preset lacks them."""- from specify_cli.presets import PresetManager- import json-- # Core template with scripts- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "wrap-test.md").write_text(- "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh\n---\n\n"- "Run: {SCRIPT}\n"- )-- # Skills dir for claude- skills_dir = project_dir / ".claude" / "skills"- skills_dir.mkdir(parents=True, exist_ok=True)- skill_subdir = skills_dir / "speckit-wrap-test"- skill_subdir.mkdir()- (skill_subdir / "SKILL.md").write_text("---\nname: speckit-wrap-test\n---\n\nold\n")-- (project_dir / ".specify" / "init-options.json").write_text(- json.dumps({"ai": "claude", "ai_skills": True})- )-- manager = PresetManager(project_dir)- install_self_test_preset(manager)-- written = (skill_subdir / "SKILL.md").read_text()- # {SCRIPT} should have been resolved (not left as a literal placeholder)- assert "{SCRIPT}" not in written-- def test_register_skills_preset_scripts_take_precedence_over_core(self, project_dir):- """preset-defined scripts/agent_scripts are not overwritten by core frontmatter."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: core-run.sh\n---\n\nCore body.\n"- )-- registrar = CommandRegistrar()- body = "{CORE_TEMPLATE}"- _, core_fm = _substitute_core_template(body, "specify", project_dir, registrar)-- # Simulate preset frontmatter that already defines scripts- preset_fm = {"description": "preset", "strategy": "wrap", "scripts": {"sh": "preset-run.sh"}}- for key in ("scripts", "agent_scripts"):- if key not in preset_fm and key in core_fm:- preset_fm[key] = core_fm[key]-- # Preset's scripts must not be overwritten by core- assert preset_fm["scripts"] == {"sh": "preset-run.sh"}-- def test_register_commands_inherits_scripts_from_core(self, project_dir):- """register_commands merges scripts/agent_scripts from core and normalizes paths."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"- "Run: {SCRIPT}\n"- )-- cmd_dir = project_dir / "preset" / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- # Preset has strategy: wrap but no scripts of its own- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: wrap no scripts\nstrategy: wrap\n---\n\n"- "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"- )-- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)-- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown",- "args": "$ARGUMENTS",- "extension": ".md",- "strip_frontmatter_keys": [],- }- try:- registrar.register_commands(- "test-agent",- [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],- "test-preset",- project_dir / "preset",- project_dir,- )- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- assert "{CORE_TEMPLATE}" not in written- assert "Run:" in written- assert "scripts:" in written- assert "run.sh" in written-- def test_register_commands_toml_resolves_inherited_scripts(self, project_dir):- """TOML agents resolve {SCRIPT} from inherited core scripts when preset omits them."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"- "Run: {SCRIPT}\n"- )-- cmd_dir = project_dir / "preset" / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: toml wrap\nstrategy: wrap\n---\n\n"- "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"- )-- toml_dir = project_dir / ".gemini" / "commands"- toml_dir.mkdir(parents=True, exist_ok=True)-- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-toml-agent"] = {- "dir": str(toml_dir.relative_to(project_dir)),- "format": "toml",- "args": "{{args}}",- "extension": ".toml",- "strip_frontmatter_keys": [],- }- try:- registrar.register_commands(- "test-toml-agent",- [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],- "test-preset",- project_dir / "preset",- project_dir,- )- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (toml_dir / "speckit.specify.toml").read_text()- assert "{CORE_TEMPLATE}" not in written- assert "{SCRIPT}" not in written- assert "run.sh" in written- # args token must use TOML format, not the intermediate $ARGUMENTS- assert "$ARGUMENTS" not in written- assert "{{args}}" in written-- def test_register_commands_markdown_resolves_inherited_scripts(self, project_dir):- """Markdown agents resolve {SCRIPT} from inherited core scripts when preset omits them."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"- "Run: {SCRIPT}\n"- )+ from specify_cli import save_init_options, load_init_options- cmd_dir = project_dir / "preset" / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: markdown wrap\nstrategy: wrap\n---\n\n"- "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"- )+ save_init_options(project_dir, {"ai": "claude", "project_name": value})- agent_dir = project_dir / ".claude" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)-- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-md-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown",- "args": "$ARGUMENTS",- "extension": ".md",- "strip_frontmatter_keys": [],- }- try:- registrar.register_commands(- "test-md-agent",- [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],- "test-preset",- project_dir / "preset",- project_dir,- )- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)+ loaded = load_init_options(project_dir)+ assert loaded["project_name"] == value- written = (agent_dir / "speckit.specify.md").read_text()- assert "{CORE_TEMPLATE}" not in written- assert "{SCRIPT}" not in written- assert "run.sh" in written- assert "strategy" not in written+ def test_save_writes_real_utf8_bytes(self, project_dir):+ """The on-disk file contains real UTF-8 bytes, not ``\\uXXXX`` escapes.- def test_register_commands_markdown_converts_args_after_script_resolution(self, project_dir):- """Markdown agents re-run arg placeholder conversion after resolve_skill_placeholders.+ Pinning ``encoding="utf-8"`` on ``write_text`` only makes a+ difference when the serialiser actually emits non-ASCII+ characters. With ``ensure_ascii=False`` on ``json.dumps`` the+ non-ASCII bytes hit the file, so the encoding pin is the thing+ that decides between cp1252 garbage and clean UTF-8 on Windows.- resolve_skill_placeholders injects $ARGUMENTS (via {ARGS} expansion). A second- _convert_argument_placeholder call must convert those to the agent's native format.+ This test pins that behaviour: the on-disk bytes are valid UTF-8+ and contain the multi-byte encoding of ``cafΓ©``, not its+ ``\\u00e9`` escape form. Reviewers can verify that removing+ ``ensure_ascii=False`` or ``encoding="utf-8"`` from the writer+ breaks this test, which is what Copilot's review pointed out the+ original round-trip test failed to do."""- from specify_cli.agents import CommandRegistrar- import copy-- core_dir = project_dir / ".specify" / "templates" / "commands"- core_dir.mkdir(parents=True, exist_ok=True)- (core_dir / "specify.md").write_text(- "---\ndescription: core\nscripts:\n sh: .specify/scripts/run.sh {ARGS}\n---\n\n"- "Run: {SCRIPT}\n"- )-- cmd_dir = project_dir / "preset" / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)- (cmd_dir / "speckit.specify.md").write_text(- "---\ndescription: forge wrap\nstrategy: wrap\n---\n\n"- "## Pre\n\n{CORE_TEMPLATE}\n\n## Post\n"- )+ from specify_cli import save_init_options- agent_dir = project_dir / ".forge" / "commands"- agent_dir.mkdir(parents=True, exist_ok=True)-- registrar = CommandRegistrar()- original = copy.deepcopy(registrar.AGENT_CONFIGS)- registrar.AGENT_CONFIGS["test-forge-agent"] = {- "dir": str(agent_dir.relative_to(project_dir)),- "format": "markdown",- "args": "{{parameters}}",- "extension": ".md",- "strip_frontmatter_keys": [],- }- try:- registrar.register_commands(- "test-forge-agent",- [{"name": "speckit.specify", "file": "commands/speckit.specify.md"}],- "test-preset",- project_dir / "preset",- project_dir,- )- finally:- CommandRegistrar.AGENT_CONFIGS.clear()- CommandRegistrar.AGENT_CONFIGS.update(original)-- written = (agent_dir / "speckit.specify.md").read_text()- assert "{SCRIPT}" not in written- assert "run.sh" in written- # $ARGUMENTS injected by resolve_skill_placeholders must be re-converted- assert "$ARGUMENTS" not in written- assert "{{parameters}}" in written-- def test_extension_command_resolves_via_extension_directory(self, project_dir):- """Extension commands (e.g. speckit.git.feature) resolve from the extension directory.-- Both _register_skills and register_commands pass the full cmd_name to- _substitute_core_template, which tries the full name first via PresetResolver- and finds speckit.git.feature.md in the extension commands directory.- """- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar+ save_init_options(project_dir, {"project_name": "cafΓ©"})- # Place the template where a real extension would install it- ext_cmd_dir = project_dir / ".specify" / "extensions" / "git" / "commands"- ext_cmd_dir.mkdir(parents=True, exist_ok=True)- (ext_cmd_dir / "speckit.git.feature.md").write_text(- "---\ndescription: git feature core\n---\n\n# Git Feature Core\n"+ opts_file = project_dir / ".specify" / "init-options.json"+ raw = opts_file.read_bytes()+ # 'cafΓ©' in UTF-8 ends with bytes 0xC3 0xA9 ('Γ©'). The cp1252+ # encoding of 'Γ©' is the single byte 0xE9. The JSON-escape form+ # would be the 6-byte literal '\\u00e9'. We assert the UTF-8 form+ # is present so the test pins the actual contract.+ assert b"caf\xc3\xa9" in raw, (+ "Expected UTF-8 bytes for 'cafΓ©' in the on-disk file, "+ f"got: {raw!r}")- # Ensure a hyphenated or dot-separated fallback does NOT exist- assert not (project_dir / ".specify" / "templates" / "commands" / "git.feature.md").exists()- assert not (project_dir / ".specify" / "templates" / "commands" / "git-feature.md").exists()-- registrar = CommandRegistrar()- body = "## Wrapper\n\n{CORE_TEMPLATE}\n"-- # Both call sites now pass the full cmd_name- result, _ = _substitute_core_template(body, "speckit.git.feature", project_dir, registrar)-- assert "# Git Feature Core" in result- assert "{CORE_TEMPLATE}" not in result+ # And the whole file decodes cleanly as UTF-8.+ raw.decode("utf-8")- def test_extension_command_resolves_via_manifest_when_filename_differs(self, project_dir):- """Extension commands whose filename differs from the command name resolve via extension.yml.+ def test_load_returns_empty_on_locale_corrupted_file(self, project_dir):+ """A file written in a non-UTF-8 codec falls back to {}, not crash.- The selftest extension maps speckit.selftest.extension β commands/selftest.md.- Name-based lookup would look for commands/speckit.selftest.extension.md and fail;- manifest-based lookup must find the actual file declared in the manifest.+ Simulates a file produced by an old client (or by a peer machine+ with a different default locale) that contains bytes invalid as+ UTF-8. ``load_init_options`` should fall back to ``{}`` per the+ existing contract β never propagate a raw ``UnicodeDecodeError``+ to the CLI surface."""- from specify_cli.presets import _substitute_core_template- from specify_cli.agents import CommandRegistrar-- ext_dir = project_dir / ".specify" / "extensions" / "selftest"- cmd_dir = ext_dir / "commands"- cmd_dir.mkdir(parents=True, exist_ok=True)-- # File is named selftest.md, NOT speckit.selftest.extension.md- (cmd_dir / "selftest.md").write_text(- "---\ndescription: selftest core\n---\n\n# Selftest Core\n"- )- # Manifest maps the command name to the actual file- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: selftest\n name: Self-Test\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " commands:\n"- " - name: speckit.selftest.extension\n"- " file: commands/selftest.md\n"- " description: Selftest command\n"- )-- registrar = CommandRegistrar()- body = "## Wrapper\n\n{CORE_TEMPLATE}\n"- result, _ = _substitute_core_template(body, "speckit.selftest.extension", project_dir, registrar)+ from specify_cli import load_init_options- assert "# Selftest Core" in result- assert "{CORE_TEMPLATE}" not in result+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ # 0xE9 is 'Γ©' in cp1252 but an invalid lead byte in UTF-8.+ opts_file.write_bytes(b'{"project_name": "caf\xe9"}')- def test_extension_template_resolves_via_manifest_when_filename_differs(self, project_dir):- """provides.templates entries resolve via extension.yml when the file- doesn't sit at the conventional path.+ assert load_init_options(project_dir) == {}- Regression coverage for #4010: manifest-declared templates/scripts- must actually be consulted by the resolver, not just accepted by- manifest validation.- """- ext_dir = project_dir / ".specify" / "extensions" / "reportext"- tmpl_dir = ext_dir / "templates" / "nested"- tmpl_dir.mkdir(parents=True, exist_ok=True)-- # File lives at a path convention-based lookup (templates/<name>.md)- # would never find.- (tmpl_dir / "actual.md").write_text("# Report Scaffold\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: reportext\n name: Report Ext\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " templates:\n"- " - name: report-scaffold\n"- " file: templates/nested/actual.md\n"- " description: Report scaffold\n"- )+ @pytest.mark.parametrize("payload", ["[]", '"value"', "42", "true", "null"])+ def test_load_returns_empty_on_non_object_json(self, project_dir, payload):+ from specify_cli import load_init_options- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("report-scaffold", "template")- assert layers, "expected the manifest-declared template to resolve"- assert layers[0]["path"] == tmpl_dir / "actual.md"- assert layers[0]["strategy"] == "replace"-- def test_extension_script_resolves_via_manifest_when_filename_differs(self, project_dir):- """provides.scripts entries resolve via extension.yml when the file- doesn't sit at the conventional path."""- ext_dir = project_dir / ".specify" / "extensions" / "collectext"- script_dir = ext_dir / "scripts" / "bash"- script_dir.mkdir(parents=True, exist_ok=True)-- # File is under scripts/bash/, not directly under scripts/, so- # convention-based lookup (scripts/<name>.sh) would never find it.- (script_dir / "collect.sh").write_text("#!/usr/bin/env bash\necho collect\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: collectext\n name: Collect Ext\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " scripts:\n"- " - name: myext-collect\n"- " file: scripts/bash/collect.sh\n"- " description: Data-collection helper\n"- " runtimes: [bash]\n"- )+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.write_text(payload, encoding="utf-8")- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("myext-collect", "script")- assert layers, "expected the manifest-declared script to resolve"- assert layers[0]["path"] == script_dir / "collect.sh"- assert layers[0]["strategy"] == "replace"-- def test_extension_template_convention_lookup_unaffected_when_undeclared(self, project_dir):- """An extension template with no manifest entry still resolves via- the pre-existing filename convention (no regression)."""- ext_dir = project_dir / ".specify" / "extensions" / "conventionext"- tmpl_dir = ext_dir / "templates"- tmpl_dir.mkdir(parents=True, exist_ok=True)- (tmpl_dir / "legacy-template.md").write_text("# Legacy Template\n")- # No extension.yml at all -- purely convention-based, unregistered extension.+ assert load_init_options(project_dir) == {}- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("legacy-template", "template")- assert layers, "expected convention-based lookup to still find the template"- assert layers[0]["path"] == tmpl_dir / "legacy-template.md"-- def test_extension_manifest_wins_over_stale_conventional_file(self, project_dir):- """A declared entry is authoritative even when a stale file also sits at- the conventional path (templates/<name>.md) β the manifest must win,- not the convention lookup, per #4010's acceptance criteria."""- ext_dir = project_dir / ".specify" / "extensions" / "bothpathsext"- (ext_dir / "templates").mkdir(parents=True, exist_ok=True)- (ext_dir / "custom").mkdir(parents=True, exist_ok=True)-- # Stale file at the conventional path -- must NOT win.- (ext_dir / "templates" / "report-scaffold.md").write_text("# Stale\n")- # Declared file at a non-conventional path -- must win.- (ext_dir / "custom" / "bar.md").write_text("# Actual\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: bothpathsext\n name: Both Paths Ext\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " templates:\n"- " - name: report-scaffold\n"- " file: custom/bar.md\n"- " description: Report scaffold\n"- )+ def test_load_returns_empty_on_unicode_decode_error(self, project_dir, monkeypatch):+ from specify_cli import load_init_options- resolver = PresetResolver(project_dir)+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.write_bytes(b"{}")- layers = resolver.collect_all_layers("report-scaffold", "template")- assert layers, "expected the manifest-declared template to resolve"- assert layers[0]["path"] == ext_dir / "custom" / "bar.md"-- resolved = resolver.resolve("report-scaffold", "template")- assert resolved == ext_dir / "custom" / "bar.md"-- with_source = resolver.resolve_with_source("report-scaffold", "template")- assert with_source["path"] == str(ext_dir / "custom" / "bar.md")-- def test_extension_manifest_declared_but_missing_file_does_not_fall_back(self, project_dir):- """A declared entry whose file is missing is authoritative -- the- resolver must not silently mask the typo by falling back to a- conventional file that happens to also exist."""- ext_dir = project_dir / ".specify" / "extensions" / "missingfileext"- (ext_dir / "scripts").mkdir(parents=True, exist_ok=True)-- # A conventional file exists, but the manifest declares a different,- # non-existent file for the same name.- (ext_dir / "scripts" / "myext-collect.sh").write_text("#!/usr/bin/env bash\necho legacy\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: missingfileext\n name: Missing File Ext\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " scripts:\n"- " - name: myext-collect\n"- " file: scripts/does-not-exist.sh\n"- " description: Data-collection helper\n"- )+ original_read_text = Path.read_text- resolver = PresetResolver(project_dir)+ def raise_decode_error(path, *args, **kwargs):+ if path == opts_file:+ raise UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte")+ return original_read_text(path, *args, **kwargs)- assert resolver.collect_all_layers("myext-collect", "script") == []- assert resolver.resolve("myext-collect", "script") is None-- def test_extension_script_resolve_and_resolve_with_source_parity(self, project_dir):- """resolve() and resolve_with_source() must find a manifest-declared- script at a non-conventional path, matching collect_all_layers()."""- ext_dir = project_dir / ".specify" / "extensions" / "collectext2"- script_dir = ext_dir / "scripts" / "bash"- script_dir.mkdir(parents=True, exist_ok=True)-- (script_dir / "collect.sh").write_text("#!/usr/bin/env bash\necho collect\n")- (ext_dir / "extension.yml").write_text(- "schema_version: '1.0'\n"- "extension:\n id: collectext2\n name: Collect Ext 2\n version: 1.0.0\n"- " description: test\n author: test\n repository: https://example.com\n"- " license: MIT\n"- "requires:\n speckit_version: '>=0.2.0'\n"- "provides:\n"- " scripts:\n"- " - name: myext-collect2\n"- " file: scripts/bash/collect.sh\n"- " description: Data-collection helper\n"- " runtimes: [bash]\n"- )+ monkeypatch.setattr(Path, "read_text", raise_decode_error)- resolver = PresetResolver(project_dir)+ assert load_init_options(project_dir) == {}- resolved = resolver.resolve("myext-collect2", "script")- assert resolved == script_dir / "collect.sh"-- with_source = resolver.resolve_with_source("myext-collect2", "script")- assert with_source is not None- assert with_source["path"] == str(script_dir / "collect.sh")- assert with_source["source"] == "extension:collectext2 (unregistered)"---# ===== _replay_wraps_for_command Tests =====--def _make_wrap_preset_dir(- base: Path,- preset_id: str,- cmd_name: str,- pre: str,- post: str,- aliases: list[str] | None = None,- file_rel: str | None = None,-) -> Path:- """Create a minimal wrap-strategy preset directory for testing."""- preset_dir = base / preset_id- cmd_dir = preset_dir / "commands"- cmd_dir.mkdir(parents=True)- file_rel = file_rel or f"commands/{cmd_name}.md"- template = {- "type": "command",- "name": cmd_name,- "file": file_rel,- "description": f"{preset_id} wrap",- }- if aliases is not None:- template["aliases"] = aliases- manifest = {- "schema_version": "1.0",- "preset": {- "id": preset_id,- "name": preset_id,- "version": "1.0.0",- "description": f"Preset {preset_id}",- "author": "test",- "repository": "https://example.com",- "license": "MIT",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [template]- },- "tags": [],- }- import yaml as _yaml- (preset_dir / "preset.yml").write_text(_yaml.dump(manifest))- command_path = preset_dir / file_rel- command_path.parent.mkdir(parents=True, exist_ok=True)- command_path.write_text(- f"---\ndescription: {preset_id} wrap\nstrategy: wrap\n---\n\n"- f"[{pre}]\n\n{{CORE_TEMPLATE}}\n\n[{post}]\n"+ @pytest.mark.parametrize(+ ("value", "expected"),+ [+ (True, True),+ (False, False),+ ("true", False),+ ("false", False),+ (1, False),+ (0, False),+ (None, False),+ ],)- return preset_dir----class TestCompositionStrategyValidation:- """Test strategy field validation in PresetManifest."""-- def test_valid_replace_strategy(self, temp_dir, valid_pack_data):- """Test that replace strategy is accepted."""- valid_pack_data["provides"]["templates"][0]["strategy"] = "replace"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- (temp_dir / "templates").mkdir(exist_ok=True)- (temp_dir / "templates" / "spec-template.md").write_text("test")- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "replace"-- def test_valid_prepend_strategy(self, temp_dir, valid_pack_data):- """Test that prepend strategy is accepted for templates."""- valid_pack_data["provides"]["templates"][0]["strategy"] = "prepend"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- (temp_dir / "templates").mkdir(exist_ok=True)- (temp_dir / "templates" / "spec-template.md").write_text("test")- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "prepend"-- def test_valid_append_strategy(self, temp_dir, valid_pack_data):- """Test that append strategy is accepted for templates."""- valid_pack_data["provides"]["templates"][0]["strategy"] = "append"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- (temp_dir / "templates").mkdir(exist_ok=True)- (temp_dir / "templates" / "spec-template.md").write_text("test")- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "append"-- def test_valid_wrap_strategy(self, temp_dir, valid_pack_data):- """Test that wrap strategy is accepted for templates."""- valid_pack_data["provides"]["templates"][0]["strategy"] = "wrap"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- (temp_dir / "templates").mkdir(exist_ok=True)- (temp_dir / "templates" / "spec-template.md").write_text("test")- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "wrap"-- def test_default_strategy_is_replace(self, pack_dir):- """Test that omitting strategy defaults to replace (key is absent)."""- manifest = PresetManifest(pack_dir / "preset.yml")- # Strategy key should not be present in the manifest data- assert "strategy" not in manifest.templates[0]- # But consumers should treat missing strategy as "replace"- assert manifest.templates[0].get("strategy", "replace") == "replace"-- def test_invalid_strategy_rejected(self, temp_dir, valid_pack_data):- """Test that invalid strategy values are rejected."""- valid_pack_data["provides"]["templates"][0]["strategy"] = "merge"- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid strategy"):- PresetManifest(manifest_path)-- def test_prepend_rejected_for_scripts(self, temp_dir, valid_pack_data):- """Test that prepend strategy is rejected for scripts."""- valid_pack_data["provides"]["templates"] = [{- "type": "script",- "name": "create-new-feature",- "file": "scripts/create-new-feature.sh",- "strategy": "prepend",- }]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):- PresetManifest(manifest_path)-- def test_append_rejected_for_scripts(self, temp_dir, valid_pack_data):- """Test that append strategy is rejected for scripts."""- valid_pack_data["provides"]["templates"] = [{- "type": "script",- "name": "create-new-feature",- "file": "scripts/create-new-feature.sh",- "strategy": "append",- }]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- with pytest.raises(PresetValidationError, match="Invalid strategy.*for script"):- PresetManifest(manifest_path)-- def test_wrap_accepted_for_scripts(self, temp_dir, valid_pack_data):- """Test that wrap strategy is accepted for scripts."""- valid_pack_data["provides"]["templates"] = [{- "type": "script",- "name": "create-new-feature",- "file": "scripts/create-new-feature.sh",- "strategy": "wrap",- }]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "wrap"-- def test_replace_accepted_for_scripts(self, temp_dir, valid_pack_data):- """Test that replace strategy is accepted for scripts."""- valid_pack_data["provides"]["templates"] = [{- "type": "script",- "name": "create-new-feature",- "file": "scripts/create-new-feature.sh",- "strategy": "replace",- }]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "replace"-- def test_prepend_accepted_for_commands(self, temp_dir, valid_pack_data):- """Test that prepend strategy is accepted for commands."""- valid_pack_data["provides"]["templates"] = [{- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- "strategy": "prepend",- }]- manifest_path = temp_dir / "preset.yml"- with open(manifest_path, 'w') as f:- yaml.dump(valid_pack_data, f)- manifest = PresetManifest(manifest_path)- assert manifest.templates[0]["strategy"] == "prepend"---class TestResolveContent:- """Test PresetResolver.resolve_content() composition."""-- def test_resolve_content_core_template(self, project_dir):- """Test resolve_content returns core template when no composition."""- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Core Spec Template" in content-- def test_resolve_content_nonexistent(self, project_dir):- """Test resolve_content returns None for nonexistent template."""- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("nonexistent")- assert content is None-- def test_resolve_content_unreadable_winning_layer_returns_none(self, project_dir):- """An undecodable winning layer must yield None, not a raw traceback.-- ``collect_all_layers`` deliberately keeps a non-UTF-8 legacy command- layer (with its ``replace`` default) so unrelated commands still- resolve. ``resolve_content`` then read that same file without a- boundary, so the tolerated layer crashed with ``UnicodeDecodeError``- at composition time β reachable from ``specify preset add`` via- ``_register_commands``. The documented contract is "Composed content- string, or None if not found".- """- presets_dir = project_dir / ".specify" / "presets"- command_path = (- presets_dir / "legacy-pack" / "commands" / "speckit.legacy.md"- )- command_path.parent.mkdir(parents=True)- command_path.write_bytes(b"\xff\xfe")- PresetRegistry(presets_dir).add(- "legacy-pack", {"version": "1.0.0", "priority": 10}- )-- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("speckit.legacy", "command")- assert content is None-- def test_resolve_content_unreadable_base_under_composing_layer(- self, project_dir, temp_dir, valid_pack_data- ):- """An undecodable base beneath a valid composing layer yields None.-- Covers the base-read guard: the winning layer composes (append), so- resolution reads the base layer beneath it β here the core template,- corrupted to non-UTF-8 β and must return None instead of crashing.- """- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "append-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")-- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")-- core_spec = project_dir / ".specify" / "templates" / "spec-template.md"- core_spec.write_bytes(b"\xff\xfe")+ def test_is_ai_skills_enabled_requires_boolean_true(self, value, expected):+ from specify_cli._init_options import is_ai_skills_enabled- resolver = PresetResolver(project_dir)- assert resolver.resolve_content("spec-template") is None+ assert is_ai_skills_enabled({"ai_skills": value}) is expected- def test_resolve_content_unreadable_composing_layer(- self, project_dir, temp_dir, valid_pack_data, monkeypatch- ):- """An unreadable composing layer over a valid base yields None.- Covers the composition-loop read and the ``OSError`` half of the- boundary: the base (core template) reads fine, but the append layer- raises a mocked ``PermissionError`` β mocked so the case also holds- under privileged CI where permission bits are not enforced.- """- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "append-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")+class TestResolveActiveAgentForRegistration:+ """Tests for the shared #2948 active-agent resolution helper.- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ ``load_init_options`` collapses "no file", "corrupted file", and+ "valid file with no active agent" into the same ``{}``. Extensions and+ presets both need to tell those apart: no file means "legacy project,+ fall back to all detected agents"; a corrupted or malformed file means+ "fail closed, register nothing" so a corrupted init-options.json can't+ silently reintroduce all-agent registration.+ """- layer_path = (- project_dir / ".specify" / "presets" / "append-pack"- / "templates" / "spec-template.md"+ def test_missing_file_returns_sentinel(self, project_dir):+ from specify_cli._init_options import (+ MISSING_INIT_OPTIONS_FILE,+ resolve_active_agent_for_registration,)- assert layer_path.is_file()- original_read_text = Path.read_text- def failing_read_text(self_path, *args, **kwargs):- if self_path == layer_path:- raise PermissionError(13, "Permission denied")- return original_read_text(self_path, *args, **kwargs)+ assert (+ resolve_active_agent_for_registration(project_dir)+ is MISSING_INIT_OPTIONS_FILE+ )- monkeypatch.setattr(Path, "read_text", failing_read_text)+ def test_valid_active_agent_returns_string(self, project_dir):+ from specify_cli import save_init_options+ from specify_cli._init_options import resolve_active_agent_for_registration- resolver = PresetResolver(project_dir)- assert resolver.resolve_content("spec-template") is None+ save_init_options(project_dir, {"ai": "claude"})- def test_resolve_content_replace_strategy(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with default replace strategy."""- manager = PresetManager(project_dir)- manager.install_from_directory(- _create_pack(temp_dir, valid_pack_data, "replace-pack",- "# Replaced Content\n"),- "0.1.5"- )+ assert resolve_active_agent_for_registration(project_dir) == "claude"- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Replaced Content" in content- assert "Core Spec Template" not in content-- def test_resolve_content_append_strategy(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with append strategy."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "append-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Appended Section\n")+ def test_corrupted_json_fails_closed(self, project_dir):+ """A present-but-unparseable file must not behave like "no file"."""+ from specify_cli._init_options import resolve_active_agent_for_registration- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.write_text("{bad json", encoding="utf-8")- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Core Spec Template" in content- assert "Appended Section" in content- # Core should come first, appended after- assert content.index("Core Spec Template") < content.index("Appended Section")-- def test_resolve_content_prepend_strategy(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with prepend strategy."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "prepend-pack", "name": "Prepend"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "prepend",- }]- }- pack_dir = temp_dir / "prepend-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Security Header\n")+ assert resolve_active_agent_for_registration(project_dir) is None- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ @pytest.mark.parametrize("value", [[], {}, "", 0, None, ["claude"]])+ def test_malformed_ai_value_fails_closed(self, project_dir, value):+ """A recorded but non-string/empty ``ai`` value fails closed too."""+ from specify_cli import save_init_options+ from specify_cli._init_options import resolve_active_agent_for_registration- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Security Header" in content- assert "Core Spec Template" in content- # Prepended content should come first- assert content.index("Security Header") < content.index("Core Spec Template")-- def test_resolve_content_wrap_strategy(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with wrap strategy for templates."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-pack", "name": "Wrap"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "wrap",- }]- }- pack_dir = temp_dir / "wrap-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text(- "# Wrapper Start\n\n{CORE_TEMPLATE}\n\n# Wrapper End\n"- )+ save_init_options(project_dir, {"ai": value})- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ assert resolve_active_agent_for_registration(project_dir) is None- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Wrapper Start" in content- assert "Core Spec Template" in content- assert "Wrapper End" in content- # Wrapper should surround core- assert content.index("Wrapper Start") < content.index("Core Spec Template")- assert content.index("Core Spec Template") < content.index("Wrapper End")-- def test_resolve_content_wrap_strategy_script(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with wrap strategy for scripts uses $CORE_SCRIPT."""- # Create core script- scripts_dir = project_dir / ".specify" / "templates" / "scripts"- scripts_dir.mkdir(parents=True, exist_ok=True)- (scripts_dir / "test-script.sh").write_text("echo 'core script'\n")-- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "script-wrap", "name": "Script Wrap"}- pack_data["provides"] = {- "templates": [{- "type": "script",- "name": "test-script",- "file": "scripts/test-script.sh",- "strategy": "wrap",- }]- }- pack_dir = temp_dir / "script-wrap"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "scripts").mkdir()- (pack_dir / "scripts" / "test-script.sh").write_text(- "#!/bin/bash\necho 'before'\n$CORE_SCRIPT\necho 'after'\n"- )+ def test_dangling_symlink_fails_closed(self, project_dir):+ """A dangling init-options.json symlink must fail closed, not fall+ back to "no file" (#2948).- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ ``Path.exists()`` follows symlinks and returns False for a broken+ symlink whose target is missing, so a naive presence check treats a+ dangling symlink the same as "no file at all" and falls back to+ legacy all-agent registration. The path is present (just broken),+ so it must be treated as a corrupted file and fail closed instead.+ """+ from specify_cli._init_options import resolve_active_agent_for_registration- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("test-script", "script")- assert content is not None- assert "echo 'before'" in content- assert "echo 'core script'" in content- assert "echo 'after'" in content-- def test_resolve_content_multi_preset_chain(self, project_dir, temp_dir, valid_pack_data):- """Test multi-preset composition chain: prepend + append stacking."""- # Create preset A (priority 1): prepend security header- pack_a_data = {**valid_pack_data}- pack_a_data["preset"] = {**valid_pack_data["preset"], "id": "preset-a", "name": "A"}- pack_a_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "prepend",- }]- }- pack_a_dir = temp_dir / "preset-a"- pack_a_dir.mkdir()- with open(pack_a_dir / "preset.yml", 'w') as f:- yaml.dump(pack_a_data, f)- (pack_a_dir / "templates").mkdir()- (pack_a_dir / "templates" / "spec-template.md").write_text("## Security Header\n")-- # Create preset B (priority 2): append compliance footer- pack_b_data = {**valid_pack_data}- pack_b_data["preset"] = {**valid_pack_data["preset"], "id": "preset-b", "name": "B"}- pack_b_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_b_dir = temp_dir / "preset-b"- pack_b_dir.mkdir()- with open(pack_b_dir / "preset.yml", 'w') as f:- yaml.dump(pack_b_data, f)- (pack_b_dir / "templates").mkdir()- (pack_b_dir / "templates" / "spec-template.md").write_text("## Compliance Footer\n")+ opts_file = project_dir / ".specify" / "init-options.json"+ opts_file.parent.mkdir(parents=True, exist_ok=True)+ opts_file.symlink_to(project_dir / ".specify" / "does-not-exist.json")- manager = PresetManager(project_dir)- manager.install_from_directory(pack_a_dir, "0.1.5", priority=1)- manager.install_from_directory(pack_b_dir, "0.1.5", priority=2)+ assert not opts_file.exists() # sanity: this is what makes it dangling+ assert opts_file.is_symlink()+ assert resolve_active_agent_for_registration(project_dir) is None- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- # Result: <security header> + <core> + <compliance footer>- assert "Security Header" in content- assert "Core Spec Template" in content- assert "Compliance Footer" in content- assert content.index("Security Header") < content.index("Core Spec Template")- assert content.index("Core Spec Template") < content.index("Compliance Footer")-- def test_resolve_content_override_trumps_composition(self, project_dir, temp_dir, valid_pack_data):- """Test that project overrides trump composition (replace at top priority)."""- # Install a composing preset- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "append-pack", "name": "Append"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "append-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Appended\n")- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+LEAN_PRESET_DIR = Path(__file__).parent.parent / "presets" / "lean"- # Create project override (replaces everything)- overrides_dir = project_dir / ".specify" / "templates" / "overrides"- overrides_dir.mkdir(parents=True)- (overrides_dir / "spec-template.md").write_text("# Override Only\n")- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content is not None- assert "Override Only" in content- # Override replaces, so appended content should not be visible- assert "Core Spec Template" not in content-- def test_resolve_content_command_type(self, project_dir, temp_dir, valid_pack_data):- """Test resolve_content with command template type."""- # Create core command using stem naming (matches real layout: plan.md, not speckit.plan.md)- commands_dir = project_dir / ".specify" / "templates" / "commands"- commands_dir.mkdir(parents=True, exist_ok=True)- (commands_dir / "plan.md").write_text("# Core Plan Command\n")-- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "cmd-append", "name": "CmdAppend"}- pack_data["provides"] = {- "templates": [{- "type": "command",- "name": "speckit.plan",- "file": "commands/speckit.plan.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "cmd-append"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "commands").mkdir()- (pack_dir / "commands" / "speckit.plan.md").write_text("## Additional Instructions\n")+CORE_CONSTITUTION_COMMAND = (+ Path(__file__).parent.parent / "templates" / "commands" / "constitution.md"+)- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("speckit.plan", "command")- assert content is not None- assert "Core Plan Command" in content- assert "Additional Instructions" in content-- def test_resolve_content_command_frontmatter_stripping(self, project_dir, temp_dir, valid_pack_data):- """Test that command composition strips frontmatter from lower layers- and reattaches only the highest-priority frontmatter."""- # Create core command with frontmatter- commands_dir = project_dir / ".specify" / "templates" / "commands"- commands_dir.mkdir(parents=True, exist_ok=True)- (commands_dir / "check.md").write_text(- "---\ndescription: Core check command\n---\nCore body content\n"- )+LEAN_COMMAND_NAMES = [+ "speckit.specify",+ "speckit.plan",+ "speckit.tasks",+ "speckit.implement",+ "speckit.constitution",+]- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "fm-test", "name": "FmTest"}- pack_data["provides"] = {- "templates": [{- "type": "command",- "name": "speckit.check",- "file": "commands/speckit.check.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "fm-test"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "commands").mkdir()- (pack_dir / "commands" / "speckit.check.md").write_text(- "---\ndescription: Preset check override\n---\nPreset body content\n"- )- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ "command_path",+ [+ CORE_CONSTITUTION_COMMAND,+ LEAN_PRESET_DIR / "commands" / "speckit.constitution.md",+ ],+ ids=["core", "lean"],+)+def test_constitution_commands_guard_against_non_governance_work(command_path):+ """Constitution commands defer non-governance work instead of executing it."""+ content = command_path.read_text()+ lower_content = content.lower()+ normalized_content = " ".join(lower_content.split())- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("speckit.check", "command")- assert content is not None- # Should have the preset (highest-priority) frontmatter- assert "Preset check override" in content- # Should have both bodies- assert "Core body content" in content- assert "Preset body content" in content- # Core frontmatter should NOT appear in the body- assert content.count("---") == 2 # only one frontmatter block (opening + closing)-- def test_resolve_content_blank_line_separator(self, project_dir, temp_dir, valid_pack_data):- """Test that prepend/append use blank line separator."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "sep-test", "name": "SepTest"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "sep-test"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("appended")+ assert "## Scope Guard" in content+ assert "**MUST NOT**" in content+ assert "Classify every part" in content+ assert "application source files" in content+ assert "non-governance intent" in content+ assert "`Next Actions`" in content+ assert "__SPECKIT_COMMAND_SPECIFY__" in content+ assert "omit" in lower_content+ assert "do not invoke it" in normalized_content or "without invoking it" in normalized_content- manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- # Should have blank line separator- assert "\n\n" in content-- def test_resolve_content_replace_over_wrap(self, project_dir, temp_dir, valid_pack_data):- """Top-priority replace layer should win even if a lower layer uses wrap."""- # Install a low-priority wrap preset (with no placeholder β would fail if evaluated)- wrap_data = {**valid_pack_data}- wrap_data["preset"] = {**valid_pack_data["preset"], "id": "wrap-lo", "name": "WrapLo"}- wrap_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "wrap",- }]- }- wrap_dir = temp_dir / "wrap-lo"- wrap_dir.mkdir()- with open(wrap_dir / "preset.yml", "w") as f:- yaml.dump(wrap_data, f)- (wrap_dir / "templates").mkdir()- # Intentionally missing {CORE_TEMPLATE} β would error if composition ran- (wrap_dir / "templates" / "spec-template.md").write_text("wrapper without placeholder")+def test_core_constitution_command_resolves_template_at_runtime():+ """The core command must consume the composed scaffold on every invocation."""+ content = CORE_CONSTITUTION_COMMAND.read_text()- manager = PresetManager(project_dir)- manager.install_from_directory(wrap_dir, "0.1.5", priority=10)-- # Install a high-priority replace preset- rep_data = {**valid_pack_data}- rep_data["preset"] = {**valid_pack_data["preset"], "id": "rep-hi", "name": "RepHi"}- rep_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- }]- }- rep_dir = temp_dir / "rep-hi"- rep_dir.mkdir()- with open(rep_dir / "preset.yml", "w") as f:- yaml.dump(rep_data, f)- (rep_dir / "templates").mkdir()- (rep_dir / "templates" / "spec-template.md").write_text("# Replaced content\n")-- manager.install_from_directory(rep_dir, "0.1.5", priority=1)+ assert "resolve-template.sh constitution-template --json" in content+ assert "resolve-template.ps1 constitution-template -Json" in content+ assert "resolve_template.py constitution-template --json" in content+ assert "parse `TEMPLATE_CONTENT` as the active template" in content+ assert "do not continue with only one contributing" in content+ assert "Do not write back to any versioned template layer" in content- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("spec-template")- assert content == "# Replaced content\n"-- @pytest.mark.parametrize("strategy", ["append", "prepend", "wrap"])- def test_resolve_content_rewrites_extension_base_subdir_paths(- self, project_dir, temp_dir, strategy- ):- """Composing over an extension-provided base command must resolve the- extension's own subdir references (agents/, knowledge-base/) to their- installed location (#2101), not just when the extension wins outright.- """- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")- (extension_dir / "commands" / "cmd.md").write_text(- "---\ndescription: Extension fakeext cmd\n---\n\n"- "Read agents/control/commander.md for context.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- preset_dir = temp_dir / f"ext-base-{strategy}"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- overlay_body = (- "{CORE_TEMPLATE}\n## Extra\n" if strategy == "wrap" else "## Extra\n"- )- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- f"---\ndescription: Preset overlay\n---\n\n{overlay_body}"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": f"ext-base-{strategy}",- "name": "Ext Base",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- "strategy": strategy,- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")+def test_core_checklist_command_resolves_template_at_runtime():+ """The checklist command must consume the composed scaffold."""+ content = (CORE_CONSTITUTION_COMMAND.parent / "checklist.md").read_text(+ encoding="utf-8"+ )- resolver = PresetResolver(project_dir)- content = resolver.resolve_content("speckit.fakeext.cmd", "command")- assert content is not None- assert ".specify/extensions/fakeext/agents/control/commander.md" in content- assert "Read agents/control" not in content- assert "## Extra" in content+ assert "--template checklist-template" in content+ assert "TEMPLATE_CONTENT" in content+ assert "Use TEMPLATE_CONTENT as the structural template" in content-class TestCollectAllLayers:- """Test PresetResolver.collect_all_layers() method."""+class TestLeanPreset:+ """Tests for the lean preset that ships with the repo."""- def test_non_utf8_legacy_command_keeps_replace_strategy(self, project_dir):- presets_dir = project_dir / ".specify" / "presets"- command_path = (- presets_dir / "legacy-pack" / "commands" / "speckit.legacy.md"- )- command_path.parent.mkdir(parents=True)- command_path.write_bytes(b"\xff\xfe")- PresetRegistry(presets_dir).add(- "legacy-pack", {"version": "1.0.0", "priority": 10}- )+ def test_lean_preset_exists(self):+ """Verify the lean preset directory and manifest exist."""+ assert LEAN_PRESET_DIR.exists()+ assert (LEAN_PRESET_DIR / "preset.yml").exists()- layers = PresetResolver(project_dir).collect_all_layers(- "speckit.legacy", "command"- )+ def test_lean_manifest_valid(self):+ """Verify the lean preset manifest is valid."""+ manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")+ assert manifest.id == "lean"+ assert manifest.name == "Lean Workflow"+ assert manifest.version == "1.0.0"+ assert len(manifest.templates) == 5 # 5 commands- assert layers[0]["path"] == command_path- assert layers[0]["strategy"] == "replace"+ def test_lean_provides_core_workflow_commands(self):+ """Verify the lean preset provides overrides for core workflow commands."""+ manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")+ provided_names = {t["name"] for t in manifest.templates}+ for name in LEAN_COMMAND_NAMES:+ assert name in provided_names, f"Lean preset missing command: {name}"- def test_single_core_layer(self, project_dir):- """Test collecting layers with only core template."""- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("spec-template")- assert len(layers) == 1- assert layers[0]["source"] == "core"- assert layers[0]["strategy"] == "replace"+ def test_lean_command_files_exist(self):+ """Verify that all declared command files actually exist on disk."""+ manifest = PresetManifest(LEAN_PRESET_DIR / "preset.yml")+ for tmpl in manifest.templates:+ tmpl_path = LEAN_PRESET_DIR / tmpl["file"]+ assert tmpl_path.exists(), f"Missing command file: {tmpl['file']}"- def test_layers_include_presets(self, project_dir, temp_dir, valid_pack_data):- """Test that layers include installed preset."""- manager = PresetManager(project_dir)- pack_dir = _create_pack(temp_dir, valid_pack_data, "test-pack",- "# From Pack\n")- manager.install_from_directory(pack_dir, "0.1.5")+ def test_lean_commands_have_no_scripts(self):+ """Verify lean commands have no scripts in frontmatter."""+ from specify_cli.agents import CommandRegistrar- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("spec-template")- assert len(layers) == 2- # Highest priority first- assert "test-pack" in layers[0]["source"]- assert layers[1]["source"] == "core"-- def test_layers_order_matches_priority(self, project_dir, temp_dir, valid_pack_data):- """Test that layers are ordered by priority (highest first)."""- manager = PresetManager(project_dir)- for pid, prio in [("pack-lo", 10), ("pack-hi", 1)]:- d = {**valid_pack_data}- d["preset"] = {**valid_pack_data["preset"], "id": pid, "name": pid}- p = temp_dir / pid- p.mkdir()- with open(p / "preset.yml", 'w') as f:- yaml.dump(d, f)- (p / "templates").mkdir()- (p / "templates" / "spec-template.md").write_text(f"# {pid}\n")- manager.install_from_directory(p, "0.1.5", priority=prio)+ for name in LEAN_COMMAND_NAMES:+ cmd_path = LEAN_PRESET_DIR / "commands" / f"speckit.{name.split('.')[-1]}.md"+ content = cmd_path.read_text()+ frontmatter, _ = CommandRegistrar.parse_frontmatter(content)+ assert "scripts" not in frontmatter, f"{name} should not have scripts in frontmatter"- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("spec-template")- assert len(layers) == 3 # pack-hi, pack-lo, core- assert "pack-hi" in layers[0]["source"]- assert "pack-lo" in layers[1]["source"]- assert layers[2]["source"] == "core"-- def test_layers_read_strategy_from_manifest(self, project_dir, temp_dir, valid_pack_data):- """Test that layers read strategy from preset manifest."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": "strat-pack", "name": "Strat"}- pack_data["provides"] = {- "templates": [{- "type": "template",- "name": "spec-template",- "file": "templates/spec-template.md",- "strategy": "append",- }]- }- pack_dir = temp_dir / "strat-pack"- pack_dir.mkdir()- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)- (pack_dir / "templates").mkdir()- (pack_dir / "templates" / "spec-template.md").write_text("## Footer\n")+ def test_lean_commands_have_no_hooks(self):+ """Verify lean commands do not contain extension hook boilerplate."""+ for name in LEAN_COMMAND_NAMES:+ cmd_path = LEAN_PRESET_DIR / "commands" / f"speckit.{name.split('.')[-1]}.md"+ content = cmd_path.read_text()+ assert "hooks." not in content, f"{name} should not reference extension hooks"+ assert "extensions.yml" not in content, f"{name} should not reference extensions.yml"+ def test_install_lean_preset(self, project_dir):+ """Test installing the lean preset from its directory."""manager = PresetManager(project_dir)- manager.install_from_directory(pack_dir, "0.1.5")+ manifest = manager.install_from_directory(LEAN_PRESET_DIR, "0.6.0")+ assert manifest.id == "lean"+ assert manager.registry.is_installed("lean")++ def test_lean_overrides_commands(self, project_dir):+ """Test that lean preset overrides are resolved correctly."""+ manager = PresetManager(project_dir)+ manager.install_from_directory(LEAN_PRESET_DIR, "0.6.0")resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("spec-template")- # Preset layer should have strategy=append- assert layers[0]["strategy"] == "append"- # Core layer should be replace- assert layers[1]["strategy"] == "replace"---class TestRemoveReconciliation:- """Test that removing a preset re-registers the next layer's command."""-- def test_remove_restores_extension_command_subdir_paths_for_non_skill_agent(- self, project_dir, temp_dir- ):- """When a preset override of an extension command is removed, the- reconciled non-skill-agent command file should have the extension's- own subdir references rewritten to their installed location (#2101),- not left as bare, unresolvable paths."""- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")- (extension_dir / "commands" / "cmd.md").write_text(- "---\ndescription: Extension fakeext cmd\n---\n\n"- "Read agents/control/commander.md for context.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)+ for name in LEAN_COMMAND_NAMES:+ result = resolver.resolve(name, template_type="command")+ assert result is not None, f"Lean override for {name} not resolved"- manager = PresetManager(project_dir)- preset_dir = temp_dir / "ext-cmd-override"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Override fakeext cmd\n---\n\npreset override content\n"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": "ext-cmd-override",- "name": "Ext Cmd Override",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)-- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_files = list(gemini_dir.glob("*fakeext*"))- assert cmd_files, "Command file should exist in gemini dir"- assert "preset override content" in cmd_files[0].read_text()-- manager.remove("ext-cmd-override")-- cmd_files = list(gemini_dir.glob("*fakeext*"))- assert cmd_files, "Command file should still exist after removal"- content = cmd_files[0].read_text()- assert "preset override content" not in content- assert ".specify/extensions/fakeext/agents/control/commander.md" in content- assert "Read agents/control" not in content-- def test_install_composes_extension_command_and_rewrites_subdir_paths_for_non_skill_agent(- self, project_dir, temp_dir- ):- """When a preset overlays (append) an extension-provided base command,- the initial composed non-skill-agent command file must have the- extension's own subdir references rewritten to their installed- location (#2101), matching the live repro: extension body- 'Read agents/control/commander.md', preset appends to- speckit.fakeext.cmd, generated Gemini content retains the bare path."""- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- extension_dir = project_dir / ".specify" / "extensions" / "fakeext"- (extension_dir / "commands").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control").mkdir(parents=True, exist_ok=True)- (extension_dir / "agents" / "control" / "commander.md").write_text("# Commander\n")- (extension_dir / "commands" / "cmd.md").write_text(- "---\ndescription: Extension fakeext cmd\n---\n\n"- "Read agents/control/commander.md for context.\n"- )- extension_manifest = {- "schema_version": "1.0",- "extension": {- "id": "fakeext",- "name": "Fake Extension",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "commands": [- {- "name": "speckit.fakeext.cmd",- "file": "commands/cmd.md",- "description": "Fake extension command",- }- ]- },- }- with open(extension_dir / "extension.yml", "w") as f:- yaml.dump(extension_manifest, f)-- preset_dir = temp_dir / "ext-cmd-append"- preset_dir.mkdir()- (preset_dir / "commands").mkdir()- (preset_dir / "commands" / "speckit.fakeext.cmd.md").write_text(- "---\ndescription: Append fakeext cmd\n---\n\n## Extra\n"- )- preset_manifest = {- "schema_version": "1.0",- "preset": {- "id": "ext-cmd-append",- "name": "Ext Cmd Append",- "version": "1.0.0",- "description": "Test",- },- "requires": {"speckit_version": ">=0.1.0"},- "provides": {- "templates": [- {- "type": "command",- "name": "speckit.fakeext.cmd",- "file": "commands/speckit.fakeext.cmd.md",- "strategy": "append",- }- ]- },- }- with open(preset_dir / "preset.yml", "w") as f:- yaml.dump(preset_manifest, f)+class TestBundledPresetLocator:+ """Tests for _locate_bundled_preset discovery function."""- manager = PresetManager(project_dir)- manager.install_from_directory(preset_dir, "0.1.5")-- cmd_files = list(gemini_dir.glob("*fakeext*"))- assert cmd_files, "Command file should exist in gemini dir"- content = cmd_files[0].read_text()- assert ".specify/extensions/fakeext/agents/control/commander.md" in content- assert "Read agents/control" not in content- assert "## Extra" in content-- def test_remove_restores_lower_priority_command(- self, project_dir, temp_dir, valid_pack_data- ):- """After removing the top-priority preset, the next preset's command- should be re-registered in agent directories."""- manager = PresetManager(project_dir)+ def test_locate_bundled_lean_preset(self):+ """_locate_bundled_preset finds the lean preset."""+ from specify_cli import _locate_bundled_preset- # Create a gemini commands dir so reconciliation writes there- gemini_dir = project_dir / ".gemini" / "commands"- gemini_dir.mkdir(parents=True)-- # Install a low-priority preset with a command- lo_data = {**valid_pack_data}- lo_data["preset"] = {- **valid_pack_data["preset"],- "id": "lo-preset",- "name": "Lo",- }- lo_data["provides"] = {- "templates": [{- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- }]- }- lo_dir = temp_dir / "lo-preset"- lo_dir.mkdir()- with open(lo_dir / "preset.yml", "w") as f:- yaml.dump(lo_data, f)- (lo_dir / "commands").mkdir()- (lo_dir / "commands" / "speckit.specify.md").write_text(- "---\ndescription: lo\n---\nLo content\n"- )- manager.install_from_directory(lo_dir, "0.1.5", priority=10)-- # Install a high-priority preset overriding the same command- hi_data = {**valid_pack_data}- hi_data["preset"] = {- **valid_pack_data["preset"],- "id": "hi-preset",- "name": "Hi",- }- hi_data["provides"] = {- "templates": [{- "type": "command",- "name": "speckit.specify",- "file": "commands/speckit.specify.md",- }]- }- hi_dir = temp_dir / "hi-preset"- hi_dir.mkdir()- with open(hi_dir / "preset.yml", "w") as f:- yaml.dump(hi_data, f)- (hi_dir / "commands").mkdir()- (hi_dir / "commands" / "speckit.specify.md").write_text(- "---\ndescription: hi\n---\nHi content\n"- )- manager.install_from_directory(hi_dir, "0.1.5", priority=1)+ path = _locate_bundled_preset("lean")+ assert path is not None+ assert (path / "preset.yml").is_file()- # Verify the hi-preset's content is active in agent dir- cmd_files = list(gemini_dir.glob("*specify*"))- assert cmd_files, "Command file should exist in gemini dir"- assert "Hi content" in cmd_files[0].read_text()+ def test_locate_bundled_preset_not_found(self):+ """_locate_bundled_preset returns None for nonexistent preset."""+ from specify_cli import _locate_bundled_preset- # Remove the high-priority preset- manager.remove("hi-preset")+ path = _locate_bundled_preset("nonexistent-preset")+ assert path is None- # The low-priority preset's command should now be in the resolution stack- resolver = PresetResolver(project_dir)- layers = resolver.collect_all_layers("speckit.specify", "command")- assert len(layers) >= 1- assert "lo-preset" in layers[0]["source"]-- # Verify on-disk agent command file switched to lo-preset content- cmd_files = list(gemini_dir.glob("*specify*"))- assert cmd_files, "Command file should still exist after removal"- assert "Lo content" in cmd_files[0].read_text()---def _create_pack(temp_dir, valid_pack_data, pack_id, content,- strategy="replace", template_type="template",- template_name="spec-template"):- """Helper to create a preset pack directory."""- pack_data = {**valid_pack_data}- pack_data["preset"] = {**valid_pack_data["preset"], "id": pack_id, "name": pack_id}-- tmpl_entry = {- "type": template_type,- "name": template_name,- }- if template_type == "script":- tmpl_entry["file"] = f"scripts/{template_name}.sh"- elif template_type == "command":- tmpl_entry["file"] = f"commands/{template_name}.md"- else:- tmpl_entry["file"] = f"templates/{template_name}.md"- if strategy != "replace":- tmpl_entry["strategy"] = strategy- pack_data["provides"] = {"templates": [tmpl_entry]}-- pack_dir = temp_dir / pack_id- pack_dir.mkdir(exist_ok=True)- with open(pack_dir / "preset.yml", 'w') as f:- yaml.dump(pack_data, f)-- if template_type == "script":- subdir = pack_dir / "scripts"- subdir.mkdir(exist_ok=True)- (subdir / f"{template_name}.sh").write_text(content)- elif template_type == "command":- subdir = pack_dir / "commands"- subdir.mkdir(exist_ok=True)- (subdir / f"{template_name}.md").write_text(content)- else:- subdir = pack_dir / "templates"- subdir.mkdir(exist_ok=True)- (subdir / f"{template_name}.md").write_text(content)-- return pack_dir---def test_preset_wrapper_resolves_ghes_asset_when_host_configured(tmp_path, monkeypatch):- """End-to-end wiring for presets: auth.json github host β GHES asset resolution."""- from specify_cli.authentication import http as _auth_http- from specify_cli.authentication.config import AuthConfigEntry- from specify_cli.presets import PresetCatalog-- monkeypatch.setattr(_auth_http, "_config_override", [- AuthConfigEntry(hosts=("ghes.example",), provider="github",- auth="bearer", token="t"),- ])- catalog = PresetCatalog(tmp_path)-- captured = []-- @contextmanager- def fake_open(url, timeout=None, extra_headers=None):- captured.append(url)- resp = MagicMock()- resp.read.side_effect = io.BytesIO(json.dumps({- "assets": [{"name": "pack.zip",- "url": "https://ghes.example/api/v3/repos/o/r/releases/assets/9"}]- }).encode()).read- yield resp-- monkeypatch.setattr(catalog, "_open_url", fake_open)-- resolved = catalog._resolve_github_release_asset_api_url(- "https://ghes.example/o/r/releases/download/v2/pack.zip"- )- assert resolved == "https://ghes.example/api/v3/repos/o/r/releases/assets/9"- assert captured == ["https://ghes.example/api/v3/repos/o/r/releases/tags/v2"]+ def test_locate_bundled_preset_rejects_invalid_id(self):+ """_locate_bundled_preset rejects IDs with invalid characters."""+ from specify_cli import _locate_bundled_preset+ assert _locate_bundled_preset("../escape") is None+ assert _locate_bundled_preset("UPPERCASE") is None+ assert _locate_bundled_preset("has spaces") is None-# ===== ensure_constitution_from_template resolver-awareness =====+ def test_bundled_preset_in_catalog(self):+ """Verify the lean preset is listed in catalog.json with bundled marker."""+ catalog_path = Path(__file__).parent.parent / "presets" / "catalog.json"+ catalog = json.loads(catalog_path.read_text())+ assert "lean" in catalog["presets"]+ assert catalog["presets"]["lean"]["bundled"] is True+ assert "download_url" not in catalog["presets"]["lean"]class TestEnsureConstitutionResolverAware:@@ -12793,14 +725,6 @@ class TestEnsureConstitutionResolverAware:assert "[PROJECT_NAME]" in content--------class TestConstitutionSyncPreset:"""The bundled opt-in ``constitution-sync`` preset re-adds materialization.