Skip to content

đź’« Toolkit to help you get started with SDD or any other process!

41.4 KB
Raw Blame
"""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 .._install_ignore import load_install_ignore
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 _command_registrar(self):
        from ..agents import CommandRegistrar
        return CommandRegistrar(self.project_root, include_generic=False)

    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)

        from ..integrations._file_changes import after_file_change, before_file_change, changing_file

        dest_dir = self.presets_dir / manifest.id
        installed = self.registry.is_installed(manifest.id)
        if installed and not force:
            raise PresetError(
                f"Preset '{manifest.id}' is already installed. "
                f"Use 'specify preset remove {manifest.id}' first."
            )
        # Validate before remove() changes registry/agent artifacts or deleting
        # an unregistered destination left behind by an earlier installation.
        ignore_fn = load_install_ignore(source_dir, ".presetignore", PresetValidationError)
        before_file_change(dest_dir, removal=True)
        try:
            if installed:
                self.remove(manifest.id)
            if dest_dir.exists():
                shutil.rmtree(dest_dir)
            shutil.copytree(source_dir, dest_dir, ignore=ignore_fn)
        finally:
            after_file_change(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():
                    with changing_file(dest_dir, removal=True):
                        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,
        expected_id: str | None = None,
        expected_version: 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"
                )

            if expected_id is not None or expected_version is not None:
                manifest = PresetManifest(manifest_path)
                if expected_id is not None and manifest.id != expected_id:
                    raise PresetValidationError(
                        f"Preset archive ID '{manifest.id}' does not match catalog ID '{expected_id}'."
                    )
                if expected_version is not None:
                    try:
                        matches_version = (
                            pkg_version.Version(manifest.version)
                            == pkg_version.Version(expected_version)
                        )
                    except (pkg_version.InvalidVersion, TypeError):
                        raise PresetValidationError(
                            f"Invalid expected catalog version: {expected_version!r}"
                        ) from None
                    if not matches_version:
                        raise PresetValidationError(
                            f"Preset archive version '{manifest.version}' does not match catalog version '{expected_version}'."
                        )

            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,
        expected_id: str | None = None,
        expected_version: 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,
            expected_id=expected_id,
            expected_version=expected_version,
        )

    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:
            _CommandRegistrarForScope = self._command_registrar()
        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:
                CommandRegistrar = self._command_registrar()
            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