Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

44.5 KB
Raw Blame
"""Artifact inventory and catalog logic. No Typer decorators.

Two public entry points:

* :meth:`ArtifactCatalog.list_artifacts` β€” flat inventory (id, name, kind, description).
* :meth:`ArtifactCatalog.get_artifact_info` β€” one row plus its full ordered stack.

Everything else in this module is internal machinery. Callers outside the
artifact command modules should not import the private helpers.
"""

from __future__ import annotations

import re
import shlex
from collections.abc import Iterable
from pathlib import Path, PurePosixPath, PureWindowsPath
from typing import Any, Literal

import yaml

from ._identifiers import (
    IdentifierComponentError,
    derive_hook_lookup_id,
    derive_hook_public_id,
    derive_public_id,
    parse_hook_artifact_name,
    parse_lookup_id,
    validate_component,
)
from .models import (
    AmbiguousArtifactError,
    Artifact,
    ArtifactKind,
    ArtifactNotFoundError,
    ArtifactResolutionError,
    ContributionNotFoundError,
    HookArtifact,
    HookStackEntry,
    NotASpecKitProjectError,
)
from .resolution import (
    _build_stack,
    _layer_provenance,
    _repo_relative_existing_file,
)

_TEMPLATE_SUFFIX = ".md"
_SCRIPT_SUFFIX = ".sh"


def _resolve_script_reference(script_root: Path, token: str) -> Path | None:
    """Resolve a command script reference that remains inside *script_root*."""
    posix_path = PurePosixPath(token)
    windows_path = PureWindowsPath(token)
    if posix_path.anchor or windows_path.anchor:
        return None
    if ".." in posix_path.parts or ".." in windows_path.parts:
        return None

    relative = Path(token)
    if relative.parts and relative.parts[0] == "scripts":
        relative = Path(*relative.parts[1:])
    if not relative.parts:
        return None

    try:
        resolved_root = script_root.resolve()
        candidate = (resolved_root / relative).resolve()
        candidate.relative_to(resolved_root)
    except (OSError, ValueError):
        return None
    return candidate if candidate.is_file() else None


def _locate_shared_asset_dir(subdir: str) -> Path | None:
    """Locate a core asset directory without changing shared asset behavior."""
    if subdir not in {"commands", "scripts", "templates"}:
        return None

    from .._assets import _locate_core_pack, _repo_root

    core_pack = _locate_core_pack()
    bundled = core_pack / subdir if core_pack is not None else None
    source = (
        _repo_root() / "templates" / "commands"
        if subdir == "commands"
        else _repo_root() / subdir
    )
    for candidate in (bundled, source):
        if candidate is not None and candidate.is_dir():
            return candidate
    return None


def _project_core_asset_root(project_root: Path | None, subdir: str) -> Path | None:
    """Return the project-local built-in-tier directory for an asset family, if present."""
    if project_root is None:
        return None
    if subdir not in {"commands", "scripts", "templates"}:
        return None  # pragma: no cover β€” internal misuse
    from ..presets import PresetResolver  # lazy: avoids circular import

    candidate = PresetResolver(project_root).templates_dir
    if subdir != "templates":
        candidate = candidate / subdir
    return candidate if candidate.is_dir() else None


def _core_command_logical_name(stem: str) -> str:
    return stem if stem.startswith("speckit.") else f"speckit.{stem}"


def _extract_frontmatter_description(text: str) -> str:
    """Return the ``description`` value from YAML frontmatter, else ``""``.

    Matches the frontmatter shape used by every core command/template on disk:
    a ``---`` fence pair at the top of the file with a YAML mapping between
    them. Anything malformed silently yields the empty string β€” the contract
    forbids omission but permits ``""``.
    """
    lines = text.splitlines(keepends=True)
    if not lines or lines[0].rstrip("\r\n") != "---":
        return ""
    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 ""
    try:
        data = yaml.safe_load("".join(lines[1:fence_end]))
    except yaml.YAMLError:
        return ""
    if not isinstance(data, dict):
        return ""
    value = data.get("description", "")
    return value if isinstance(value, str) else ""


def _extract_script_description(text: str) -> str:
    """Return the first docstring/comment line of a script, else ``""``.

    Supports the three script runtimes Spec Kit ships:

    * Python (``.py``): the first line of the module docstring.
    * Bash (``.sh``): the first ``#``-prefixed comment line following the
      shebang.
    * PowerShell (``.ps1``): either the first line of a ``<# ... #>`` block
      comment or the first ``#``-prefixed line.

    Anything unrecognized yields the empty string.
    """
    py_match = re.match(r'^(?:#![^\n]*\n)?\s*(?:"""|\'\'\')(.*?)(?:"""|\'\'\')', text, re.DOTALL)
    if py_match:
        first = py_match.group(1).strip().splitlines()
        if first:
            return first[0].strip()

    ps_block = re.match(r'^(?:<#\s*(.*?)#>)', text, re.DOTALL)
    if ps_block:
        first = ps_block.group(1).strip().splitlines()
        if first:
            return first[0].strip().lstrip(".").strip()

    for raw in text.splitlines():
        stripped = raw.strip()
        if not stripped or stripped.startswith("#!"):
            continue
        if stripped.startswith("#"):
            return stripped.lstrip("#").strip()
        break
    return ""


def _describe_artifact_file(path: Path, kind: ArtifactKind) -> str:
    """Return the on-disk description for an artifact file, else ``""``.

    Routes to the same extractors the inventory uses so a project
    override reports its own metadata instead of inheriting the description
    of the core/preset layer it hides.
    """
    try:
        text = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError):
        return ""
    if kind == "script":
        return _extract_script_description(text)
    return _extract_frontmatter_description(text)


# ---------------------------------------------------------------------------
# ArtifactCatalog β€” public faΓ§ade
# ---------------------------------------------------------------------------


def _validate_project(project_root: Path) -> None:
    """Raise NotASpecKitProjectError when ``project_root`` isn't a Spec Kit project.

    The two invariants the rest of the module relies on are that
    ``project_root`` exists and that a ``.specify/`` subdirectory sits under
    it. Anything else β€” missing presets/, missing extensions/, missing
    templates/ β€” is a valid empty-inventory scenario and is not treated as
    an error.
    """
    if not (project_root / ".specify").is_dir():
        raise NotASpecKitProjectError()


def _validate_extension_registry(project_root: Path) -> None:
    extensions_dir = project_root / ".specify" / "extensions"
    if not extensions_dir.exists():
        return

    from ..extensions import ExtensionRegistry

    if ExtensionRegistry(extensions_dir).is_corrupt():
        raise ArtifactResolutionError()


def _resolve_kind_hint(name: str, kind: ArtifactKind | None) -> tuple[str, ArtifactKind | None]:
    """Parse ``kind:name`` shorthand and reconcile it with an explicit ``--kind`` flag.

    Returns ``(bare_name, resolved_kind)``. When ``name`` uses the ``kind:name``
    grammar and ``kind`` is also set explicitly, the two must agree β€” a
    mismatch is treated as an unknown artifact.
    """
    if kind == "hook":
        if name.startswith("hook:"):
            candidate = name.removeprefix("hook:")
            try:
                parse_hook_artifact_name(candidate)
            except IdentifierComponentError:
                pass
            else:
                return candidate, "hook"
        return name, "hook"

    if ":" in name:
        prefix, _, bare = name.partition(":")
        if prefix in ("command", "template", "script"):
            resolved: ArtifactKind = prefix  # type: ignore[assignment]
            if kind is not None and kind != resolved:
                raise ArtifactNotFoundError(name)
            return bare, resolved
        if prefix == "hook":
            if kind is not None and kind != "hook":
                raise ArtifactNotFoundError(name)
            return bare, "hook"
    return name, kind


def _validate_artifact_name(name: str, kind: ArtifactKind) -> str:
    """Validate the structural identifier component constraints for ``name``."""
    if kind == "hook":
        try:
            parse_hook_artifact_name(name)
        except IdentifierComponentError as exc:
            raise ArtifactNotFoundError(name) from exc
        return name
    try:
        return validate_component(name, f"{kind} name")
    except IdentifierComponentError as exc:
        raise ArtifactNotFoundError(name) from exc


def _is_valid_artifact_name_component(name: Any, kind: ArtifactKind) -> bool:
    """Return ``True`` when ``name`` can appear in an artifact identifier."""
    try:
        validate_component(name, f"{kind} name")
    except IdentifierComponentError:
        return False
    return True


class ArtifactCatalog:
    """Read-only view over one Spec Kit project's artifact inventory."""

    def __init__(self, project_root: Path) -> None:
        self.project_root = project_root

    # ------------------------------------------------------------------ list
    def list_artifacts(self) -> list[Artifact | HookArtifact]:
        """Return every artifact Spec Kit exposes for this project, deduped.

        Named artifacts are sorted by kind and name. Hook artifacts follow in
        their deterministic event, priority, and declaration order.
        Returns an empty list when no artifacts are found rather than raising;
        a fresh install with no presets, no extensions, and no built-in assets is
        still a valid Spec Kit project.

        Skills (``.github/skills/**/SKILL.md``) are intentionally excluded β€”
        they are integration-specific output, not a shipped asset family.

        Descriptions are picked from the highest-priority layer that has one,
        not the first layer discovered β€” a built-in command that an active
        preset overrides must report the preset's description, and two
        competing packs must report the higher-precedence one's. Precedence
        is decided by :meth:`PresetResolver.collect_all_layers`'s own
        ordering (index 0 = winner), not by enumeration order here.
        """
        artifacts, _layers_cache, resolver, _manifest_cache = self._collect_inventory()
        hooks, _hook_stack_cache = self._collect_hook_inventory(resolver)
        return [*artifacts, *hooks]

    def list_artifacts_with_stack(self) -> list[dict[str, Any]]:
        """Return list rows enriched with each artifact's full composition stack."""
        artifacts, layers_cache, resolver, manifest_cache = self._collect_inventory()
        rows: list[dict[str, Any]] = []
        for artifact in artifacts:
            stack = _build_stack(
                self.project_root,
                artifact.kind,
                artifact.name,
                raw_layers=layers_cache.get((artifact.kind, artifact.name)),
                resolver=resolver,
                manifest_cache=manifest_cache,
            )
            row = artifact.to_json_dict()
            row["stack"] = [layer.to_json_dict() for layer in stack]
            rows.append(row)

        hook_rows, hook_stack_cache = self._collect_hook_inventory(resolver)
        for hook in hook_rows:
            row = hook.to_json_dict()
            row["stack"] = [
                entry.to_json_dict()
                for entry in hook_stack_cache[(hook.eventName, hook.targetCommand)]
            ]
            rows.append(row)
        return rows

    # ------------------------------------------------------------------ info
    def get_artifact_info(
        self,
        name: str,
        kind: ArtifactKind | None = None,
    ) -> dict[str, Any]:
        """Return the full JSON-ready dict for ``specify artifact info``.

        Argument resolution:

        * ``name`` accepts the ``kind:name`` grammar as shorthand; when both
          the shorthand and ``kind`` are supplied they must agree.
        * When neither the shorthand nor ``kind`` narrows the search and
          more than one kind matches ``name``, raises
          :class:`AmbiguousArtifactError`.
        * When no artifact matches, raises :class:`ArtifactNotFoundError`.
        """
        bare, resolved_kind = _resolve_kind_hint(name, kind)

        if resolved_kind == "hook":
            return self._get_hook_info(bare, original_argument=name)

        # Project and registry validation happens once, inside
        # ``_collect_inventory`` below β€” the same chokepoint ``list_artifacts``
        # uses β€” so both public methods fail closed identically instead of
        # each re-implementing the checks.
        inventory, layers_cache, resolver, manifest_cache = self._collect_inventory()
        if resolved_kind is None:
            matches = [
                (artifact.kind, artifact.name)
                for artifact in inventory
                if artifact.name == bare
            ]
            hook_rows, _hook_stack_cache = self._collect_hook_inventory(resolver)
            if any(row.name == bare for row in hook_rows):
                matches.append(("hook", bare))
            if not matches:
                raise ArtifactNotFoundError(name)
            if len(matches) > 1:
                raise AmbiguousArtifactError(bare, [k for k, _ in matches])
            resolved_kind = matches[0][0]
            if resolved_kind == "hook":
                return self._get_hook_info(
                    bare, original_argument=name, resolver=resolver
                )

        validated_name = _validate_artifact_name(bare, resolved_kind)
        artifact = next(
            (
                item
                for item in inventory
                if item.kind == resolved_kind and item.name == validated_name
            ),
            None,
        )
        if artifact is None:
            raise ArtifactNotFoundError(name)
        stack = _build_stack(
            self.project_root,
            resolved_kind,
            validated_name,
            raw_layers=layers_cache.get((resolved_kind, validated_name)),
            resolver=resolver,
            manifest_cache=manifest_cache,
        )
        if not stack:
            raise ArtifactNotFoundError(name)

        return {
            "id": derive_public_id(resolved_kind, validated_name),
            "name": validated_name,
            "kind": resolved_kind,
            "description": artifact.description,
            "stack": [layer.to_json_dict() for layer in stack],
        }

    def get_contribution_info(self, lookup_id: str) -> dict[str, Any]:
        """Resolve a stack ``lookupId`` to its validated manifest entry."""
        _validate_project(self.project_root)
        _validate_extension_registry(self.project_root)
        try:
            layer, source_id, kind, name = parse_lookup_id(lookup_id)
        except IdentifierComponentError as exc:
            raise ContributionNotFoundError(lookup_id) from exc
        if layer == "project":
            raise ContributionNotFoundError(lookup_id)

        from ..presets import PresetError, PresetResolver

        resolver = PresetResolver(self.project_root)
        try:
            if layer == "preset":
                resolved = self._find_preset_contribution(
                    resolver, source_id, kind, name
                )
            else:
                resolved = self._find_extension_contribution(
                    resolver, source_id, kind, name
                )
        except (OSError, PresetError) as exc:
            raise ArtifactResolutionError() from exc
        if resolved is None:
            raise ContributionNotFoundError(lookup_id)

        contribution, manifest_path, source_path = resolved
        return {
            "id": lookup_id,
            "layer": layer,
            "sourceId": source_id,
            "kind": kind,
            "name": name,
            "manifestPath": manifest_path,
            "sourcePath": source_path,
            "contribution": contribution,
        }

    def _find_preset_contribution(
        self,
        resolver: Any,
        source_id: str,
        kind: str,
        name: str,
    ) -> tuple[dict[str, Any], str, str | None] | None:
        for pack_id, _metadata in resolver._get_all_presets_by_priority():
            if pack_id != source_id:
                continue
            pack_dir = resolver.presets_dir / pack_id
            manifest = resolver._get_manifest(pack_dir)
            if manifest is None:
                return None
            for entry in manifest.templates:
                if (
                    isinstance(entry, dict)
                    and entry.get("type") == kind
                    and entry.get("name") == name
                ):
                    return self._contribution_result(
                        entry, pack_dir, manifest.path
                    )
        return None

    def _find_extension_contribution(
        self,
        resolver: Any,
        source_id: str,
        kind: str,
        name: str,
    ) -> tuple[dict[str, Any], str, str | None] | None:
        from ..extensions import (
            ExtensionManifest,
            ValidationError,
            coerce_hook_entries,
        )

        for _priority, extension_id, _metadata in resolver._get_all_extensions_by_priority():
            if extension_id != source_id:
                continue
            extension_dir = resolver.extensions_dir / extension_id
            manifest_path = extension_dir / "extension.yml"
            try:
                manifest = ExtensionManifest(manifest_path)
            except (ValidationError, OSError, TypeError, AttributeError):
                return None
            if kind == "hook":
                event_name, command = parse_hook_artifact_name(name)
                matching: dict[str, Any] | None = None
                hook_config = (manifest.hooks or {}).get(event_name)
                for entry in coerce_hook_entries(hook_config):
                    if isinstance(entry, dict) and entry.get("command") == command:
                        matching = entry
                if matching is None:
                    return None
                relative_manifest = _repo_relative_existing_file(
                    self.project_root, manifest.path
                )
                if relative_manifest is None:
                    raise ArtifactResolutionError()
                return (
                    {**matching, "eventName": event_name},
                    relative_manifest,
                    None,
                )

            entries = {
                "command": manifest.commands,
                "template": manifest.templates,
                "script": manifest.scripts,
            }[kind]
            for entry in entries:
                if isinstance(entry, dict) and entry.get("name") == name:
                    return self._contribution_result(
                        entry, extension_dir, manifest.path
                    )
        return None

    def _contribution_result(
        self,
        entry: dict[str, Any],
        pack_dir: Path,
        manifest_path: Path,
    ) -> tuple[dict[str, Any], str, str | None]:
        relative_manifest = _repo_relative_existing_file(
            self.project_root, manifest_path
        )
        if relative_manifest is None:
            raise ArtifactResolutionError()
        relative_file = entry.get("file")
        source_path = None
        if isinstance(relative_file, str):
            try:
                resolved_pack = pack_dir.resolve()
                candidate = pack_dir / relative_file
                candidate.resolve().relative_to(resolved_pack)
            except (OSError, ValueError):
                pass
            else:
                source_path = _repo_relative_existing_file(
                    self.project_root, candidate
                )
        return (
            dict(entry),
            relative_manifest,
            source_path,
        )

    def _get_hook_info(
        self,
        bare_name: str,
        original_argument: str,
        resolver: Any | None = None,
    ) -> dict[str, Any]:
        """Return one hook row and its additive declaration stack."""
        _validate_artifact_name(bare_name, "hook")
        event_name, command = parse_hook_artifact_name(bare_name)
        hook_rows, stack_cache = self._collect_hook_inventory(resolver)
        for row in hook_rows:
            if row.eventName != event_name or row.targetCommand != command:
                continue
            payload = row.to_json_dict()
            payload["stack"] = [
                entry.to_json_dict()
                for entry in stack_cache[(event_name, command)]
            ]
            return payload
        raise ArtifactNotFoundError(original_argument)

    def _collect_hook_inventory(
        self, resolver: Any | None = None
    ) -> tuple[
        list[HookArtifact],
        dict[tuple[str, str], list[HookStackEntry]],
    ]:
        """Project declared hooks and existing runtime bindings into artifact rows."""
        from ..extensions import (
            DEFAULT_HOOK_PRIORITY,
            ExtensionManager,
            ExtensionManifest,
            HookExecutor,
            ValidationError,
            coerce_hook_entries,
            normalize_priority,
        )
        from ..presets import PresetError, PresetResolver

        if resolver is None:
            _validate_project(self.project_root)
            _validate_extension_registry(self.project_root)
            resolver = PresetResolver(self.project_root)

        grouped: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = {}
        extension_manager = ExtensionManager(self.project_root)
        insertion_index = 0

        try:
            extensions = resolver._get_all_extensions_by_priority()
            for _resolver_priority, extension_id, metadata in extensions:
                extension_dir = resolver.extensions_dir / extension_id
                if metadata is not None:
                    manifest = extension_manager.get_extension(extension_id)
                else:
                    manifest_path = extension_dir / "extension.yml"
                    manifest = None
                    if manifest_path.is_file():
                        try:
                            manifest = ExtensionManifest(manifest_path)
                        except (
                            ValidationError,
                            OSError,
                            TypeError,
                            AttributeError,
                        ):
                            manifest = None
                if manifest is None:
                    continue

                manifest_path = _repo_relative_existing_file(
                    self.project_root, manifest.path
                )
                if manifest_path is None:
                    raise ArtifactResolutionError()
                source_id = extension_id

                for event_name, hook_config in (manifest.hooks or {}).items():
                    entries_by_command: dict[
                        str, tuple[dict[str, Any], str, str]
                    ] = {}
                    for entry in coerce_hook_entries(hook_config):
                        if not isinstance(entry, dict):
                            continue
                        command = entry.get("command")
                        try:
                            public_id = derive_hook_public_id(event_name, command)
                            lookup_id = derive_hook_lookup_id(
                                "extension", source_id, event_name, command
                            )
                        except IdentifierComponentError:
                            continue
                        entries_by_command.pop(command, None)
                        entries_by_command[command] = (
                            entry,
                            public_id,
                            lookup_id,
                        )

                    for command, entry_data in entries_by_command.items():
                        entry, public_id, lookup_id = entry_data
                        insertion_index += 1
                        declaration = {
                            "id": public_id,
                            "layer": "extension",
                            "sourceId": source_id,
                            "runtimeExtensionId": manifest.id,
                            "presetId": None,
                            "presetName": None,
                            "manifestPath": manifest_path,
                            "lookupId": lookup_id,
                            "eventName": event_name,
                            "command": command,
                            "description": entry.get("description", ""),
                            "priority": normalize_priority(
                                entry.get("priority"), DEFAULT_HOOK_PRIORITY
                            ),
                            "optional": bool(entry.get("optional", True)),
                        }
                        grouped.setdefault((event_name, command), []).append(
                            (insertion_index, declaration)
                        )
        except (OSError, PresetError) as exc:
            raise ArtifactResolutionError() from exc

        hook_executor = HookExecutor(self.project_root)
        enabled_by_event: dict[str, list[dict[str, Any]]] = {}
        rows: list[HookArtifact] = []
        stack_cache: dict[tuple[str, str], list[HookStackEntry]] = {}

        for (event_name, command), declarations in grouped.items():
            if event_name not in enabled_by_event:
                enabled_by_event[event_name] = hook_executor.get_hooks_for_event(
                    event_name
                )
            enabled_bindings = enabled_by_event[event_name]
            ordered = sorted(
                declarations,
                key=lambda item: (item[1]["priority"], item[0]),
            )
            stack_entries = [
                HookStackEntry(
                    id=declaration["id"],
                    layer="extension",
                    sourceId=declaration["sourceId"],
                    presetId=None,
                    presetName=None,
                    strategy="additive",
                    active=any(
                        binding.get("extension")
                        == declaration["runtimeExtensionId"]
                        and binding.get("command") == command
                        for binding in enabled_bindings
                    ),
                    hidden=False,
                    manifestPath=declaration["manifestPath"],
                    lookupId=declaration["lookupId"],
                    sourcePath=None,
                    priority=declaration["priority"],
                    optional=declaration["optional"],
                )
                for _index, declaration in ordered
            ]
            stack_cache[(event_name, command)] = stack_entries
            description = next(
                (
                    declaration["description"]
                    for _index, declaration in ordered
                    if isinstance(declaration["description"], str)
                    and declaration["description"]
                ),
                "",
            )
            public_id = derive_hook_public_id(event_name, command)
            rows.append(
                HookArtifact(
                    id=public_id,
                    name=public_id.removeprefix("hook:"),
                    kind="hook",
                    description=description,
                    eventName=event_name,
                    targetCommand=command,
                    registered=any(entry.active for entry in stack_entries),
                )
            )

        rows.sort(
            key=lambda row: (
                row.eventName,
                stack_cache[(row.eventName, row.targetCommand)][0].priority,
            )
        )
        return rows, stack_cache

    # -------------------------------------------------------------- internals
    def _collect_inventory(
        self,
    ) -> tuple[
        list[Artifact],
        dict[tuple[ArtifactKind, str], list[dict[str, Any]]],
        Any,
        dict[Path, Any | None],
    ]:
        _validate_project(self.project_root)
        _validate_extension_registry(self.project_root)

        from ..presets import (  # lazy: avoids circular import
            PresetError,
            PresetResolver,
        )

        resolver = PresetResolver(self.project_root)
        layers_cache: dict[tuple[ArtifactKind, str], list[dict[str, Any]]] = {}
        core_script_paths = self._selected_core_script_paths()

        def _layers_for(kind: ArtifactKind, name: str) -> list[dict[str, Any]]:
            key = (kind, name)
            if key not in layers_cache:
                try:
                    layers = resolver.collect_all_layers(name, kind)
                except (OSError, PresetError) as exc:
                    raise ArtifactResolutionError() from exc
                core_script = core_script_paths.get(name) if kind == "script" else None
                if core_script is not None and not any(
                    layer.get("source") in {"core", "core (bundled)"}
                    for layer in layers
                ):
                    layers.append(
                        {
                            "path": core_script,
                            "source": "core",
                            "strategy": "replace",
                        }
                    )
                layers_cache[key] = layers
            return layers_cache[key]

        def _has_any_replace_layer(layers: list[dict[str, Any]]) -> bool:
            return any(layer.get("strategy") == "replace" for layer in layers)

        names: set[tuple[ArtifactKind, str]] = set()
        try:
            for kind, name in self._iter_candidate_artifacts(
                resolver, core_script_paths
            ):
                key = (kind, name)
                if not _is_valid_artifact_name_component(name, kind):
                    continue
                # Resolve each candidate through Spec Kit's existing single-artifact
                # path for behavioral parity; optimize shared manifest reads only if
                # typical small extension sets show a measurable inventory cost.
                layers = _layers_for(kind, name)
                if layers and _has_any_replace_layer(layers):
                    names.add(key)
        except (OSError, PresetError) as exc:
            raise ArtifactResolutionError() from exc

        artifacts: list[Artifact] = []
        manifest_cache: dict[Path, Any | None] = {}
        for kind, name in names:
            description = ""
            for layer in _layers_for(kind, name):
                candidate = self._describe_layer(
                    resolver, layer, kind, name, manifest_cache
                )
                if candidate:
                    description = candidate
                    break
            artifacts.append(
                Artifact(
                    id=derive_public_id(kind, name),
                    name=name,
                    kind=kind,
                    description=description,
                )
            )

        kind_order = {"command": 0, "template": 1, "script": 2}
        return (
            sorted(artifacts, key=lambda a: (kind_order[a.kind], a.name)),
            layers_cache,
            resolver,
            manifest_cache,
        )

    def _iter_candidate_artifacts(
        self,
        resolver: Any,
        core_script_paths: dict[str, Path],
    ) -> Iterable[tuple[ArtifactKind, str]]:
        """Yield candidate ``(kind, name)`` pairs from every resolver tier.

        Covers the ways a pack can contribute an artifact:

        * manifest-declared entries (``preset.yml`` / ``extension.yml``), read
          through each manifest class's existing normalized properties, and
        * convention-placed extension files (``commands/``, ``templates/``,
          ``scripts/``) that the resolver picks up even without a manifest.

        Presets and extensions are enumerated through the resolver's existing
        priority helpers, so the candidate set follows the same install,
        enable, and priority rules as resolution. Project overrides and
        resolver-compatible core asset paths are included only as candidate
        names; :meth:`PresetResolver.collect_all_layers` remains the source of
        truth for which candidates are actually present and which layer wins.

        Project-local overrides under ``.specify/templates/overrides`` are
        included too, so an artifact that exists only as an override is still
        listed.

        Silent on any manifest that fails to parse β€” that would already be
        surfaced by ``specify preset list`` or ``specify extension list``, and
        this command's job is to describe the composed inventory, not to be
        the second validation surface.
        """
        from ..extensions import ExtensionManager, ExtensionManifest, ValidationError
        from ..presets import PresetManager  # lazy: avoids circular import

        # -- Presets: the registry is authoritative, no unregistered fallback.
        preset_manager = PresetManager(self.project_root)
        for pack_id, _metadata in resolver._get_all_presets_by_priority():
            pack_dir = preset_manager.presets_dir / pack_id
            manifest = preset_manager.get_pack(pack_id)
            yield from self._iter_pack_candidates(manifest, pack_dir, "preset")

        # -- Extensions: use the resolver's own extension enumeration order.
        ext_manager = ExtensionManager(self.project_root)
        for _priority, ext_id, metadata in resolver._get_all_extensions_by_priority():
            ext_dir = resolver.extensions_dir / ext_id
            if metadata is not None:
                manifest = ext_manager.get_extension(ext_id)
            else:
                manifest_path = ext_dir / "extension.yml"
                manifest = None
                if manifest_path.is_file():
                    try:
                        manifest = ExtensionManifest(manifest_path)
                    except (ValidationError, OSError, TypeError, AttributeError):
                        manifest = None
            yield from self._iter_pack_candidates(manifest, ext_dir, "extension")

        yield from self._iter_project_override_candidates(resolver)
        yield from self._iter_core_candidates(core_script_paths)

    @staticmethod
    def _iter_pack_candidates(
        manifest: Any,
        pack_dir: Path,
        layer: Literal["preset", "extension"],
    ) -> Iterable[tuple[ArtifactKind, str]]:
        """Yield manifest-declared and convention-based candidate names."""
        if manifest is not None:
            if layer == "preset":
                declarations = (
                    (entry.get("type"), entry)
                    for entry in manifest.templates
                    if isinstance(entry, dict)
                )
            else:
                declarations = (
                    (kind, entry)
                    for kind, entries in (
                        ("command", manifest.commands),
                        ("template", manifest.templates),
                        ("script", manifest.scripts),
                    )
                    for entry in entries
                    if isinstance(entry, dict)
                )
            for kind, contribution in declarations:
                name = contribution.get("name")
                if (
                    kind in ("command", "template", "script")
                    and isinstance(name, str)
                    and name
                    and ":" not in name
                ):
                    yield kind, name

        yield from ((kind, name) for kind, name, _path in _iter_convention_contributions(pack_dir))

    def _iter_project_override_candidates(
        self,
        resolver: Any,
    ) -> Iterable[tuple[ArtifactKind, str]]:
        """Yield candidate ``(kind, name)`` pairs for project overrides.

        A root ``overrides/<name>.md`` file is the override for both the
        ``template`` and the ``command`` lookup of ``<name>``. Both candidates
        are emitted and the normal inventory resolution path decides whether
        each is present.
        """
        overrides_dir = resolver.overrides_dir
        if not overrides_dir.is_dir():
            return
        for entry in sorted(overrides_dir.iterdir(), key=lambda p: p.name):
            if not entry.is_file() or entry.suffix != _TEMPLATE_SUFFIX:
                continue
            name = entry.stem
            if not _is_valid_artifact_name_component(name, "command"):
                continue
            for kind in ("command", "template"):
                yield kind, name
        scripts_dir = overrides_dir / "scripts"
        if not scripts_dir.is_dir():
            return
        for entry in sorted(scripts_dir.iterdir(), key=lambda p: p.name):
            if entry.is_file() and entry.suffix == _SCRIPT_SUFFIX:
                if not _is_valid_artifact_name_component(entry.stem, "script"):
                    continue
                yield "script", entry.stem

    def _iter_core_candidates(
        self, core_script_paths: dict[str, Path]
    ) -> Iterable[tuple[ArtifactKind, str]]:
        """Yield candidate names from resolver-compatible core asset paths."""
        from ..extensions import CORE_COMMAND_NAMES  # lazy: avoids circular import
        from ..presets import PresetResolver

        project_commands_dir = _project_core_asset_root(self.project_root, "commands")
        bundled_commands_dir = _locate_shared_asset_dir("commands")
        command_dirs = tuple(
            directory
            for directory in (project_commands_dir, bundled_commands_dir)
            if directory is not None
        )
        command_names = {_core_command_logical_name(name) for name in CORE_COMMAND_NAMES}
        for directory in command_dirs:
            for entry in sorted(directory.iterdir(), key=lambda p: p.name):
                if entry.is_file() and entry.suffix == _TEMPLATE_SUFFIX:
                    command_names.add(_core_command_logical_name(entry.stem))
        for name in sorted(command_names):
            if any(
                (directory / f"{candidate}.md").is_file()
                for directory in command_dirs
                for candidate in (
                    name,
                    *(
                        (PresetResolver._core_stem(name),)
                        if PresetResolver._core_stem(name)
                        else ()
                    ),
                )
                if candidate is not None
            ):
                yield "command", name

        seen_templates: set[str] = set()
        for directory in (
            _project_core_asset_root(self.project_root, "templates"),
            _locate_shared_asset_dir("templates"),
        ):
            if directory is None:
                continue
            for entry in sorted(directory.iterdir(), key=lambda p: p.name):
                if (
                    entry.is_file()
                    and entry.suffix == _TEMPLATE_SUFFIX
                    and entry.stem not in seen_templates
                ):
                    seen_templates.add(entry.stem)
                    yield "template", entry.stem

        for directory in (
            _project_core_asset_root(self.project_root, "scripts"),
            _locate_shared_asset_dir("scripts"),
        ):
            if directory is None:
                continue
            for entry in sorted(directory.glob(f"*{_SCRIPT_SUFFIX}"), key=lambda p: p.name):
                yield "script", entry.stem
        yield from (("script", name) for name in sorted(core_script_paths))

    def _selected_core_script_paths(self) -> dict[str, Path]:
        """Return built-in scripts selected by the project's existing runtime policy."""
        from .._init_options import load_init_options
        from ..agents import CommandRegistrar
        from ..integrations.base import IntegrationBase

        command_dirs = tuple(
            directory
            for directory in (
                _project_core_asset_root(self.project_root, "commands"),
                _locate_shared_asset_dir("commands"),
            )
            if directory is not None
        )
        script_dirs = tuple(
            directory
            for directory in (
                _project_core_asset_root(self.project_root, "scripts"),
                _locate_shared_asset_dir("scripts"),
            )
            if directory is not None
        )
        requested = load_init_options(self.project_root).get("script")
        selected: dict[str, Path] = {}

        for command_dir in command_dirs:
            for template_path in sorted(command_dir.glob("*.md"), key=lambda p: p.name):
                try:
                    content = template_path.read_text(encoding="utf-8")
                except (OSError, UnicodeDecodeError):
                    continue
                frontmatter, _body = CommandRegistrar.parse_frontmatter(content)
                scripts = frontmatter.get("scripts", {})
                if not isinstance(scripts, dict):
                    continue
                script_commands = {
                    key: value
                    for key, value in scripts.items()
                    if isinstance(key, str) and isinstance(value, str) and value.strip()
                }
                if not script_commands:
                    continue
                try:
                    variant = IntegrationBase.select_script_variant(
                        requested, script_commands
                    )
                    tokens = shlex.split(script_commands[variant], posix=True)
                except (KeyError, ValueError):
                    continue
                if not tokens:
                    continue

                path = None
                for script_dir in script_dirs:
                    path = _resolve_script_reference(script_dir, tokens[0])
                    if path is not None:
                        break
                if path is None:
                    continue
                name = path.stem.replace("_", "-") if variant == "py" else path.stem
                selected.setdefault(name, path)

        return selected

    def _describe_layer(
        self,
        resolver: Any,
        layer: dict[str, Any],
        kind: ArtifactKind,
        name: str,
        manifest_cache: dict[Path, Any | None],
    ) -> str:
        """Return manifest metadata or on-disk metadata for one resolver layer."""
        manifest_description = self._manifest_description_for_layer(
            resolver, layer, kind, name, manifest_cache
        )
        if manifest_description:
            return manifest_description
        path = layer.get("path")
        if isinstance(path, Path):
            return _describe_artifact_file(path, kind)
        return ""

    def _manifest_description_for_layer(
        self,
        resolver: Any,
        layer: dict[str, Any],
        kind: ArtifactKind,
        name: str,
        manifest_cache: dict[Path, Any | None],
    ) -> str:
        provenance = _layer_provenance(
            resolver, layer, kind, name, manifest_cache
        )
        entry = provenance.manifest_entry
        if entry is None:
            return ""
        description = entry.get("description", "")
        return description if isinstance(description, str) else ""


_CONVENTION_SUBDIRS: tuple[tuple[str, ArtifactKind, str], ...] = (
    ("commands", "command", _TEMPLATE_SUFFIX),
    ("templates", "template", _TEMPLATE_SUFFIX),
    ("scripts", "script", _SCRIPT_SUFFIX),
)


def _iter_convention_contributions(
    pack_dir: Path,
) -> Iterable[tuple[ArtifactKind, str, Path]]:
    """Yield ``(kind, name, path)`` for files exposed by convention.

    Templates are also accepted at the pack root for legacy compatibility,
    matching the resolver's ``templates/``-then-root lookup order.
    """
    for subdir, kind, suffix in _CONVENTION_SUBDIRS:
        candidate_dir = pack_dir / subdir
        if not candidate_dir.is_dir():
            continue
        for entry in sorted(candidate_dir.iterdir(), key=lambda p: p.name):
            if entry.is_file() and entry.suffix == suffix and ":" not in entry.stem:
                yield kind, entry.stem, entry
    if not pack_dir.is_dir():
        return
    for entry in sorted(pack_dir.iterdir(), key=lambda p: p.name):
        if (
            entry.is_file()
            and entry.suffix == _TEMPLATE_SUFFIX
            and ":" not in entry.stem
        ):
            yield "template", entry.stem, entry