Skip to content

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

86.0 KB
Raw Blame
"""Domain and contract tests for artifact inventory and resolution."""

from __future__ import annotations

import json
import os
import re
import shutil
from pathlib import Path

import pytest
import yaml

from specify_cli.artifacts import (
    AmbiguousArtifactError,
    Artifact,
    ArtifactCatalog,
    ArtifactKind,
    ArtifactNotFoundError,
    ArtifactResolutionError,
    ContributionNotFoundError,
    HookArtifact,
    NotASpecKitProjectError,
)
from specify_cli.artifacts.resolution import _preset_display_name
from specify_cli.extensions import CORE_COMMAND_NAMES, ExtensionRegistry
from specify_cli.presets import PresetRegistry, PresetResolver
from tests.conftest import install_preset
from tests.specify_cli.artifacts.helpers import (
    ERROR_REGEX,
    install_extension_with_hooks,
    write_hook_binding,
)


# ---------------------------------------------------------------------------
# Contract tests β€” matching artifact-list.schema.json
# ---------------------------------------------------------------------------


class TestListArtifactsContract:
    def test_returns_list_of_artifact(self, spec_kit_project: Path):
        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        assert all(isinstance(r, (Artifact, HookArtifact)) for r in rows)

    def test_every_row_has_required_fields(self, spec_kit_project: Path):
        for row in ArtifactCatalog(spec_kit_project).list_artifacts():
            d = row.to_json_dict()
            assert set(d.keys()) == {"id", "name", "kind", "description"}
            assert isinstance(d["description"], str)  # never None; empty string OK

    def test_id_grammar(self, spec_kit_project: Path):
        pattern = re.compile(
            r"^(?:(?:command|template|script):[^:]+|hook:[^:]+:[^:]+)$"
        )
        for row in ArtifactCatalog(spec_kit_project).list_artifacts():
            assert pattern.match(row.id), f"bad id: {row.id!r}"

    def test_name_never_contains_colon(self, spec_kit_project: Path):
        for row in ArtifactCatalog(spec_kit_project).list_artifacts():
            if row.kind != "hook":
                assert ":" not in row.name

    def test_kind_is_from_fixed_enum(self, spec_kit_project: Path):
        for row in ArtifactCatalog(spec_kit_project).list_artifacts():
            assert row.kind in ("command", "template", "script", "hook")

    def test_rows_are_unique(self, spec_kit_project: Path):
        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        ids = [r.id for r in rows]
        assert len(ids) == len(set(ids))

    def test_every_core_command_is_listed_and_resolvable(
        self, spec_kit_project: Path
    ):
        catalog = ArtifactCatalog(spec_kit_project)
        listed = {
            row.name for row in catalog.list_artifacts() if row.kind == "command"
        }
        expected = {f"speckit.{name}" for name in CORE_COMMAND_NAMES}

        assert expected <= listed
        for name in expected:
            info = catalog.get_artifact_info(f"command:{name}")
            assert info["id"] == f"command:{name}"
            assert info["kind"] == "command"
            assert info["stack"]

    @pytest.mark.parametrize(
        ("requested", "runtime_dir"),
        [("sh", "bash"), ("ps", "powershell"), ("py", "python")],
    )
    def test_core_scripts_follow_existing_project_runtime_selection(
        self, spec_kit_project: Path, requested: str, runtime_dir: str
    ):
        (spec_kit_project / ".specify" / "init-options.json").write_text(
            json.dumps({"script": requested}),
            encoding="utf-8",
        )
        catalog = ArtifactCatalog(spec_kit_project)
        scripts = [row for row in catalog.list_artifacts() if row.kind == "script"]

        assert {row.name for row in scripts} == {
            "check-prerequisites",
            "resolve-template",
            "setup-plan",
            "setup-tasks",
        }
        selected_paths = catalog._selected_core_script_paths()
        assert set(selected_paths) == {row.name for row in scripts}
        assert all(path.parent.name == runtime_dir for path in selected_paths.values())
        for script in scripts:
            info = catalog.get_artifact_info(script.id)
            assert info["stack"][-1]["layer"] is None
            assert info["stack"][-1]["sourceId"] is None
            assert info["stack"][-1]["lookupId"] is None
            assert info["stack"][-1]["sourcePath"] is None

    def test_core_scripts_reuse_existing_runtime_fallback(
        self, spec_kit_project: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
    ):
        commands_dir = tmp_path / "commands"
        scripts_dir = tmp_path / "scripts"
        commands_dir.mkdir()
        (scripts_dir / "bash").mkdir(parents=True)
        (commands_dir / "demo.md").write_text(
            "---\n"
            "scripts:\n"
            "  sh: scripts/bash/demo.sh\n"
            "---\n",
            encoding="utf-8",
        )
        script = scripts_dir / "bash" / "demo.sh"
        script.write_text("#!/bin/sh\n", encoding="utf-8")
        (spec_kit_project / ".specify" / "init-options.json").write_text(
            json.dumps({"script": "ps"}),
            encoding="utf-8",
        )

        monkeypatch.setattr(
            "specify_cli.artifacts.catalog._locate_shared_asset_dir",
            lambda subdir: {
                "commands": commands_dir,
                "scripts": scripts_dir,
                "templates": None,
            }[subdir],
        )

        assert ArtifactCatalog(spec_kit_project)._selected_core_script_paths() == {
            "demo": script
        }

    @pytest.mark.parametrize(
        "reference_kind",
        [
            "absolute",
            "windows-drive",
            "unc",
            "traversal",
        ],
    )
    def test_core_scripts_reject_unsafe_references(
        self,
        spec_kit_project: Path,
        tmp_path: Path,
        monkeypatch: pytest.MonkeyPatch,
        reference_kind: str,
    ):
        commands_dir = tmp_path / "commands"
        scripts_dir = tmp_path / "scripts"
        commands_dir.mkdir()
        (scripts_dir / "bash").mkdir(parents=True)
        outside = tmp_path / "outside.sh"
        outside.write_text(
            "#!/bin/sh\n# Must not be read\n", encoding="utf-8"
        )
        script_reference = {
            "absolute": outside.resolve().as_posix(),
            "windows-drive": "C:/outside/demo.sh",
            "unc": "//server/share/demo.sh",
            "traversal": "scripts/bash/../../outside.sh",
        }[reference_kind]
        (commands_dir / "demo.md").write_text(
            "---\n"
            "scripts:\n"
            f"  sh: {script_reference}\n"
            "---\n",
            encoding="utf-8",
        )
        monkeypatch.setattr(
            "specify_cli.artifacts.catalog._locate_shared_asset_dir",
            lambda subdir: {
                "commands": commands_dir,
                "scripts": scripts_dir,
                "templates": None,
            }[subdir],
        )

        catalog = ArtifactCatalog(spec_kit_project)
        assert catalog._selected_core_script_paths() == {}
        assert all(row.id != "script:outside" for row in catalog.list_artifacts())

    def test_core_scripts_reject_symlinks_escaping_script_root(
        self, spec_kit_project: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
    ):
        commands_dir = tmp_path / "commands"
        scripts_dir = tmp_path / "scripts"
        commands_dir.mkdir()
        (scripts_dir / "bash").mkdir(parents=True)
        outside = tmp_path / "outside.sh"
        outside.write_text("#!/bin/sh\n# Must not be read\n", encoding="utf-8")
        link = scripts_dir / "bash" / "demo.sh"
        try:
            link.symlink_to(outside)
        except OSError:
            pytest.skip("symlink creation is not available")
        (commands_dir / "demo.md").write_text(
            "---\n"
            "scripts:\n"
            "  sh: scripts/bash/demo.sh\n"
            "---\n",
            encoding="utf-8",
        )
        monkeypatch.setattr(
            "specify_cli.artifacts.catalog._locate_shared_asset_dir",
            lambda subdir: {
                "commands": commands_dir,
                "scripts": scripts_dir,
                "templates": None,
            }[subdir],
        )

        assert ArtifactCatalog(spec_kit_project)._selected_core_script_paths() == {}

    def test_excludes_disabled_and_unusable_manifest_contributions(
        self, spec_kit_project: Path
    ):
        extensions_dir = spec_kit_project / ".specify" / "extensions"
        for extension_id, artifact_name, enabled, file_name in (
            (
                "disabled-ext",
                "disabled-template",
                False,
                "templates/disabled-template.md",
            ),
            (
                "missing-file-ext",
                "missing-template",
                True,
                "templates/missing-template.md",
            ),
        ):
            extension_dir = extensions_dir / extension_id
            extension_dir.mkdir()
            (extension_dir / "extension.yml").write_text(
                yaml.safe_dump(
                    {
                        "schema_version": "1.0",
                        "extension": {
                            "id": extension_id,
                            "name": extension_id,
                            "version": "1.0.0",
                            "description": "test",
                            "author": "test",
                            "repository": "https://example.com",
                            "license": "MIT",
                        },
                        "requires": {"speckit_version": ">=0.2.0"},
                        "provides": {
                            "templates": [
                                {
                                    "name": artifact_name,
                                    "file": file_name,
                                    "description": "Should not be listed",
                                }
                            ]
                        },
                    }
                ),
                encoding="utf-8",
            )
            if not enabled:
                template = extension_dir / file_name
                template.parent.mkdir()
                template.write_text("# Disabled\n", encoding="utf-8")
            ExtensionRegistry(extensions_dir).add(
                extension_id, {"version": "1.0.0", "enabled": enabled}
            )

        names = {row.name for row in ArtifactCatalog(spec_kit_project).list_artifacts()}
        assert "disabled-template" not in names
        assert "missing-template" not in names

    def test_unregistered_extension_installed_id_identifies_lookup(
        self, spec_kit_project: Path
    ):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "renamed"
        ext_dir.mkdir()
        (ext_dir / "commands").mkdir()
        (ext_dir / "commands" / "actual.md").write_text(
            "---\ndescription: Manifest identity wins\n---\nbody\n",
            encoding="utf-8",
        )
        (ext_dir / "commands" / "speckit.renamed.convention.md").write_text(
            "---\ndescription: Convention identity uses directory\n---\nbody\n",
            encoding="utf-8",
        )
        (ext_dir / "extension.yml").write_text(
            yaml.safe_dump(
                {
                    "schema_version": "1.0",
                    "extension": {
                        "id": "original",
                        "name": "Original Id",
                        "version": "1.0.0",
                        "description": "test",
                        "author": "test",
                        "repository": "https://example.com",
                        "license": "MIT",
                    },
                    "requires": {"speckit_version": ">=0.2.0"},
                    "provides": {
                        "commands": [
                            {
                                "name": "speckit.original.hello",
                                "file": "commands/actual.md",
                                "description": "manifest declared command",
                            }
                        ]
                    },
                }
            ),
            encoding="utf-8",
        )

        catalog = ArtifactCatalog(spec_kit_project)
        assert "command:speckit.original.hello" in {
            row.id for row in catalog.list_artifacts()
        }
        info = catalog.get_artifact_info("speckit.original.hello")
        assert info["stack"][0]["sourceId"] == "renamed"
        assert info["stack"][0]["lookupId"] == (
            "extension:renamed:command:speckit.original.hello"
        )
        resolver_layer = PresetResolver(spec_kit_project).collect_all_layers(
            "speckit.original.hello", "command"
        )[0]
        assert "lookupId" not in resolver_layer
        # Provenance uses the installed directory identity and path even when
        # the manifest declares a different logical ID.
        assert (
            info["stack"][0]["manifestPath"]
            == ".specify/extensions/renamed/extension.yml"
        )
        contribution = catalog.get_contribution_info(
            info["stack"][0]["lookupId"]
        )
        assert contribution["id"] == info["stack"][0]["lookupId"]
        assert contribution["layer"] == "extension"
        assert contribution["sourceId"] == "renamed"
        assert contribution["kind"] == "command"
        assert contribution["name"] == "speckit.original.hello"
        assert contribution["contribution"]["file"] == "commands/actual.md"

        convention = catalog.get_artifact_info("speckit.renamed.convention")[
            "stack"
        ][0]
        assert convention["sourceId"] == "renamed"
        assert convention["lookupId"] == (
            "extension:renamed:command:speckit.renamed.convention"
        )
        assert convention["manifestPath"] is None
        with pytest.raises(ContributionNotFoundError):
            catalog.get_contribution_info(convention["lookupId"])

    def test_duplicate_extension_manifest_ids_resolve_each_installed_layer(
        self, spec_kit_project: Path
    ):
        for installed_id, description in (
            ("a-copy", "First declaration"),
            ("b-copy", "Second declaration"),
        ):
            ext_dir = (
                spec_kit_project / ".specify" / "extensions" / installed_id
            )
            (ext_dir / "commands").mkdir(parents=True)
            (ext_dir / "commands" / "shared.md").write_text(
                description, encoding="utf-8"
            )
            (ext_dir / "extension.yml").write_text(
                yaml.safe_dump(
                    {
                        "schema_version": "1.0",
                        "extension": {
                            "id": "shared",
                            "name": "Shared",
                            "version": "1.0.0",
                            "description": "test",
                            "author": "test",
                            "repository": "https://example.com",
                            "license": "MIT",
                        },
                        "requires": {"speckit_version": ">=0.2.0"},
                        "provides": {
                            "commands": [
                                {
                                    "name": "speckit.shared.command",
                                    "file": "commands/shared.md",
                                    "description": description,
                                }
                            ]
                        },
                    }
                ),
                encoding="utf-8",
            )

        catalog = ArtifactCatalog(spec_kit_project)
        stack = catalog.get_artifact_info("speckit.shared.command")["stack"]
        extension_layers = [
            layer for layer in stack if layer["layer"] == "extension"
        ]

        assert [layer["sourceId"] for layer in extension_layers] == [
            "a-copy",
            "b-copy",
        ]
        assert [layer["lookupId"] for layer in extension_layers] == [
            "extension:a-copy:command:speckit.shared.command",
            "extension:b-copy:command:speckit.shared.command",
        ]
        resolved = [
            catalog.get_contribution_info(layer["lookupId"])
            for layer in extension_layers
        ]
        assert [
            contribution["contribution"]["description"]
            for contribution in resolved
        ] == ["First declaration", "Second declaration"]
        assert [contribution["manifestPath"] for contribution in resolved] == [
            ".specify/extensions/a-copy/extension.yml",
            ".specify/extensions/b-copy/extension.yml",
        ]

    def test_includes_project_local_core_assets(self, spec_kit_project: Path):
        templates_dir = spec_kit_project / ".specify" / "templates"
        (templates_dir / "legacy-template.md").write_text(
            "---\ndescription: Local template\n---\n", encoding="utf-8"
        )
        commands_dir = templates_dir / "commands"
        commands_dir.mkdir()
        (commands_dir / "local-command.md").write_text(
            "---\ndescription: Local command\n---\n", encoding="utf-8"
        )
        scripts_dir = templates_dir / "scripts"
        scripts_dir.mkdir()
        (scripts_dir / "legacy-script.sh").write_text(
            "# Local script\n", encoding="utf-8"
        )

        catalog = ArtifactCatalog(spec_kit_project)
        artifacts = {artifact.id: artifact for artifact in catalog.list_artifacts()}

        assert artifacts["template:legacy-template"].description == "Local template"
        assert artifacts["command:speckit.local-command"].description == "Local command"
        assert artifacts["script:legacy-script"].description == "Local script"
        for name in ("speckit.local-command", "legacy-template", "legacy-script"):
            layer = catalog.get_artifact_info(name)["stack"][0]
            assert layer["layer"] is None
            assert layer["sourceId"] is None
            assert layer["lookupId"] is None
            assert layer["sourcePath"] is None

    def test_includes_root_level_pack_templates(
        self, spec_kit_project: Path
    ):
        extension_dir = spec_kit_project / ".specify" / "extensions" / "legacy"
        extension_dir.mkdir()
        (extension_dir / "legacy-root.md").write_text(
            "---\ndescription: Legacy root template\n---\n",
            encoding="utf-8",
        )
        (extension_dir / "README.md").write_text("# Packaging notes\n", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        names = {row.name for row in catalog.list_artifacts()}

        assert "legacy-root" in names
        assert "README" in names
        assert next(
            row for row in catalog.list_artifacts() if row.name == "legacy-root"
        ).description == "Legacy root template"

    def test_extension_registry_missing_collection_key_uses_existing_normalization(
        self, spec_kit_project: Path
    ):
        registry_path = spec_kit_project / ".specify" / "extensions" / ".registry"
        registry_path.write_text('{"schema_version": "1.0"}', encoding="utf-8")

        assert ArtifactCatalog(spec_kit_project).list_artifacts()

    @pytest.mark.skipif(os.name == "nt", reason="':' filenames are unsupported on Windows")
    def test_skips_invalid_colon_names_in_project_local_inventory(self, spec_kit_project: Path):
        templates_dir = spec_kit_project / ".specify" / "templates"
        commands_dir = templates_dir / "commands"
        scripts_dir = templates_dir / "scripts"
        overrides_dir = templates_dir / "overrides"
        override_scripts_dir = overrides_dir / "scripts"
        commands_dir.mkdir(parents=True)
        scripts_dir.mkdir(parents=True)
        overrides_dir.mkdir(parents=True)
        override_scripts_dir.mkdir(parents=True)

        (templates_dir / "bad:template.md").write_text("---\ndescription: bad\n---\n", encoding="utf-8")
        (commands_dir / "bad:command.md").write_text("---\ndescription: bad\n---\n", encoding="utf-8")
        (scripts_dir / "bad:script.sh").write_text("# bad\n", encoding="utf-8")
        (overrides_dir / "bad:override.md").write_text("override", encoding="utf-8")
        (override_scripts_dir / "bad:override-script.sh").write_text("# bad\n", encoding="utf-8")

        artifacts = ArtifactCatalog(spec_kit_project).list_artifacts()
        assert all(":" not in artifact.name for artifact in artifacts)

    def test_preserves_prefixed_project_local_command_names(self, spec_kit_project: Path):
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir()
        (commands_dir / "speckit.local-prefixed.md").write_text(
            "---\ndescription: Local prefixed command\n---\n", encoding="utf-8"
        )

        artifacts = {artifact.id: artifact for artifact in ArtifactCatalog(spec_kit_project).list_artifacts()}
        assert "command:speckit.local-prefixed" in artifacts
        assert "command:speckit.speckit.local-prefixed" not in artifacts

    def test_prefers_exact_core_command_name(self, spec_kit_project: Path):
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir()
        (commands_dir / "foo.md").write_text(
            "---\ndescription: Stripped fallback\n---\n", encoding="utf-8"
        )
        exact_path = commands_dir / "speckit.foo.md"
        exact_path.write_text(
            "---\ndescription: Exact logical name\n---\n", encoding="utf-8"
        )

        assert PresetResolver(spec_kit_project).resolve("speckit.foo", "command") == exact_path
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.foo")
        assert info["description"] == "Exact logical name"

    def test_active_preset_description_overrides_hidden_core_description(
        self, spec_kit_project: Path
    ):
        """A preset that overrides a core command must win the description too.

        Regression test: descriptions used to be merged "first non-empty
        wins", and core rows were inserted before contributions β€” so an
        active preset's replacement of a core command still reported the
        (now-inactive) core description.
        """
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir(parents=True)
        (commands_dir / "speckit.constitution.md").write_text(
            "---\ndescription: Core description\n---\n", encoding="utf-8"
        )

        pack = install_preset(
            spec_kit_project,
            "override-preset",
            {
                "commands": [
                    {"name": "speckit.constitution", "description": "Preset description"}
                ]
            },
        )
        (pack / "commands").mkdir()
        (pack / "commands" / "speckit.constitution.md").write_text(
            "# Preset\n", encoding="utf-8"
        )

        artifacts = {
            artifact.id: artifact
            for artifact in ArtifactCatalog(spec_kit_project).list_artifacts()
        }
        assert artifacts["command:speckit.constitution"].description == "Preset description"

    def test_higher_precedence_preset_description_wins(self, spec_kit_project: Path):
        """When two presets both provide an artifact, the winner's description wins.

        Lower ``priority`` number means higher precedence (see
        ``PresetResolver.collect_all_layers``); the loser's description must
        not leak through just because it happens to be enumerated first
        alphabetically.
        """
        pack_low = install_preset(
            spec_kit_project,
            "aaa-low-priority-preset",
            {"templates": [{"name": "shared-artifact", "description": "Loser description"}]},
            priority=20,
        )
        (pack_low / "templates").mkdir()
        (pack_low / "templates" / "shared-artifact.md").write_text(
            "# Loser\n", encoding="utf-8"
        )

        pack_high = install_preset(
            spec_kit_project,
            "zzz-high-priority-preset",
            {"templates": [{"name": "shared-artifact", "description": "Winner description"}]},
            priority=5,
        )
        (pack_high / "templates").mkdir()
        (pack_high / "templates" / "shared-artifact.md").write_text(
            "# Winner\n", encoding="utf-8"
        )

        artifacts = {
            artifact.id: artifact
            for artifact in ArtifactCatalog(spec_kit_project).list_artifacts()
        }
        assert artifacts["template:shared-artifact"].description == "Winner description"


class TestListSorting:
    """Deterministic ordering for the flat inventory."""

    def test_kind_grouping(self, spec_kit_project: Path):
        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        kinds_seen = [r.kind for r in rows]
        # kinds must appear as contiguous groups in the fixed order
        first_idx = {
            k: next((i for i, x in enumerate(kinds_seen) if x == k), None)
            for k in ("command", "template", "script", "hook")
        }
        indices = [v for v in first_idx.values() if v is not None]
        assert indices == sorted(indices)

    def test_name_sorted_within_kind(self, spec_kit_project: Path):
        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        by_kind: dict[str, list[str]] = {}
        for r in rows:
            if r.kind == "hook":
                continue
            by_kind.setdefault(r.kind, []).append(r.name)
        for _, names in by_kind.items():
            assert names == sorted(names)


class TestEmptyProject:
    def test_empty_stack_returns_empty_list(self, tmp_path: Path):
        # A .specify/ dir with no presets/extensions and no accessible core.
        # We can't easily wipe the core baseline in this process, so instead
        # verify list_artifacts is at least callable and returns a list.
        root = tmp_path / "empty"
        root.mkdir()
        (root / ".specify").mkdir()
        rows = ArtifactCatalog(root).list_artifacts()
        assert isinstance(rows, list)


# ---------------------------------------------------------------------------
# get_artifact_info contract
# ---------------------------------------------------------------------------


class TestInfoContract:
    def test_stack_ordered_highest_first(self, spec_kit_project: Path):
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        assert info["stack"], "expected at least one stack layer"

    def test_exactly_one_active_row(self, spec_kit_project: Path):
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        actives = [layer for layer in info["stack"] if layer["active"]]
        assert len(actives) == 1

    def test_active_is_index_zero(self, spec_kit_project: Path):
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        assert info["stack"][0]["active"] is True
        for layer in info["stack"][1:]:
            assert layer["active"] is False

    def test_builtin_row_shape(self, spec_kit_project: Path):
        resolver_layer = PresetResolver(spec_kit_project).collect_all_layers(
            "speckit.constitution", "command"
        )[-1]
        assert resolver_layer["source"] == "core (bundled)"
        assert "lookupId" not in resolver_layer

        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        assert info["id"] == "command:speckit.constitution"
        builtin = next(layer for layer in info["stack"] if layer["layer"] is None)
        assert builtin["sourceId"] is None
        assert builtin["presetId"] is None
        assert builtin["presetName"] is None
        assert builtin["manifestPath"] is None
        assert builtin["strategy"] == "replace"
        assert builtin["lookupId"] is None
        assert builtin["sourcePath"] is None

    def test_project_override_row_shape(self, spec_kit_project: Path):
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        overrides.mkdir()
        (overrides / "speckit.constitution.md").write_text("override", encoding="utf-8")

        info = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "command:speckit.constitution"
        )

        project = next(layer for layer in info["stack"] if layer["layer"] == "project")
        assert project["presetId"] is None
        assert project["presetName"] is None
        assert project["manifestPath"] is None
        assert project["sourcePath"] is None
        assert project["strategy"] == "replace"
        assert project["sourceId"] == "_"
        assert re.match(r"^project:_:(command|template|script):[^:]+$", project["lookupId"])

    def test_lookup_id_grammar(self, spec_kit_project: Path):
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        for layer in info["stack"]:
            if layer["lookupId"] is None:
                assert layer["layer"] is None
                assert layer["sourceId"] is None
                continue
            assert re.match(
                r"^(project|preset|extension):[^:]+:(command|template|script):[^:]+(:[0-9a-f]{12})?$",
                layer["lookupId"],
            )

    def test_id_matches_list(self, spec_kit_project: Path):
        cat = ArtifactCatalog(spec_kit_project)
        info = cat.get_artifact_info("speckit.constitution")
        assert info["id"] == "command:speckit.constitution"

    def test_every_stack_row_carries_id(self, spec_kit_project: Path):
        """Every stack row carries a non-null ``id``, including built-in rows.

        ``id`` is the source-agnostic round-trip key; it does not depend on
        the row having a ``lookupId`` (manifest-backed layer provenance).
        """
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        overrides.mkdir()
        (overrides / "speckit.constitution.md").write_text("override", encoding="utf-8")

        info = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "command:speckit.constitution"
        )
        assert len(info["stack"]) >= 2
        for layer in info["stack"]:
            assert layer["id"] == "command:speckit.constitution"


# ---------------------------------------------------------------------------
# Error conditions β€” pinned strings for the artifact-error contract
# ---------------------------------------------------------------------------


class TestErrors:
    def test_unknown_artifact_message(self, spec_kit_project: Path):
        with pytest.raises(ArtifactNotFoundError) as excinfo:
            ArtifactCatalog(spec_kit_project).get_artifact_info("no.such.thing")
        assert excinfo.value.message == "unknown artifact no.such.thing"
        assert ERROR_REGEX.match(excinfo.value.message)

    def test_not_a_project(self, non_project: Path):
        with pytest.raises(NotASpecKitProjectError) as excinfo:
            ArtifactCatalog(non_project).list_artifacts()
        assert excinfo.value.message == "not a Spec Kit project: no .specify/ directory found"
        assert ERROR_REGEX.match(excinfo.value.message)

    def test_ambiguous_artifact_message(self, spec_kit_project: Path):
        """When both a command and a template share the same bare name."""
        # Register a preset that contributes 'shared-name' as both a
        # template and a script β€” the info lookup with no kind hint should
        # then be ambiguous.
        pack = install_preset(
            spec_kit_project,
            "test-ambig",
            {
                "templates": [
                    {"type": "template", "name": "shared-name", "description": "t"},
                    {"type": "script", "name": "shared-name", "description": "s"},
                ],
            },
        )
        (pack / "templates").mkdir()
        (pack / "templates" / "shared-name.md").write_text("# Template\n")
        (pack / "scripts").mkdir()
        (pack / "scripts" / "shared-name.sh").write_text("#!/usr/bin/env bash\n")
        with pytest.raises(AmbiguousArtifactError) as excinfo:
            ArtifactCatalog(spec_kit_project).get_artifact_info("shared-name")
        assert excinfo.value.message.startswith("ambiguous artifact shared-name: matches kinds")
        assert ERROR_REGEX.match(excinfo.value.message)

    def test_resolution_error_message(self):
        assert ArtifactResolutionError().message == "artifact resolution failed"

    def test_info_rejects_corrupt_extension_registry(self, spec_kit_project: Path):
        registry = spec_kit_project / ".specify" / "extensions" / ".registry"
        registry.write_text("{invalid", encoding="utf-8")

        with pytest.raises(ArtifactResolutionError):
            ArtifactCatalog(spec_kit_project).get_artifact_info("command:speckit.constitution")

class TestKindHint:
    def test_kind_flag_disambiguates(self, spec_kit_project: Path):
        install_preset(
            spec_kit_project,
            "test-kind",
            {"templates": [{"name": "dup", "description": "t"}],
             "scripts": [{"name": "dup", "description": "s"}]},
        )
        # No stack file backs these contributions on disk so the info call
        # will raise unknown after resolving kind β€” either way it should
        # not raise ambiguous when a kind is supplied.
        try:
            ArtifactCatalog(spec_kit_project).get_artifact_info("dup", kind="template")
        except ArtifactNotFoundError:
            pass  # expected: manifest declared it but no file to compose

    def test_shorthand_grammar(self, spec_kit_project: Path):
        # Even with core commands, the shorthand should route correctly.
        info = ArtifactCatalog(spec_kit_project).get_artifact_info("command:speckit.constitution")
        assert info["kind"] == "command"

    def test_conflicting_shorthand_and_flag(self, spec_kit_project: Path):
        with pytest.raises(ArtifactNotFoundError):
            ArtifactCatalog(spec_kit_project).get_artifact_info(
                "template:speckit.constitution", kind="command"
            )

    @pytest.mark.parametrize(
        ("kind", "name"),
        (
            ("template", "../../outside"),
            ("command", "template:foo"),
            ("script", "script:name"),
        ),
    )
    def test_kind_hint_rejects_invalid_name_components(
        self, spec_kit_project: Path, kind: ArtifactKind, name: str
    ):
        with pytest.raises(ArtifactNotFoundError):
            ArtifactCatalog(spec_kit_project).get_artifact_info(name, kind=kind)

    def test_id_form_round_trips_to_same_artifact(self, spec_kit_project: Path):
        """``artifact info`` accepts the public ``id`` form (``kind:name``).

        Given either the bare name or its ``id``, the resolved artifact is
        the same β€” ``id`` is the source-agnostic round-trip key.
        """
        cat = ArtifactCatalog(spec_kit_project)
        by_bare = cat.get_artifact_info("speckit.plan")
        by_id = cat.get_artifact_info("command:speckit.plan")
        assert by_id == by_bare

    def test_id_form_resolves_template_despite_same_named_command(
        self, spec_kit_project: Path
    ):
        """``kind:name`` disambiguates when a command shares a template's name."""
        pack_dir = install_preset(
            spec_kit_project,
            "collide-pack",
            {"commands": [{"name": "spec-template", "description": "cmd"}]},
        )
        (pack_dir / "commands").mkdir(parents=True, exist_ok=True)
        (pack_dir / "commands" / "spec-template.md").write_text(
            "colliding command body", encoding="utf-8"
        )

        # Sanity check: without a kind hint, the bare name is ambiguous
        # because both a command and a template named "spec-template" exist.
        with pytest.raises(AmbiguousArtifactError):
            ArtifactCatalog(spec_kit_project).get_artifact_info("spec-template")

        info = ArtifactCatalog(spec_kit_project).get_artifact_info("template:spec-template")
        assert info["kind"] == "template"
        assert info["id"] == "template:spec-template"


# ---------------------------------------------------------------------------
# Skills exclusion
# ---------------------------------------------------------------------------


class TestSkillsExcluded:
    def test_no_skills_in_list(self, spec_kit_project: Path):
        skills_dir = spec_kit_project / ".github" / "skills" / "speckit-my-skill"
        skills_dir.mkdir(parents=True)
        (skills_dir / "SKILL.md").write_text("---\nname: my-skill\n---\nbody", encoding="utf-8")
        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        assert not any("skill" in r.name.lower() for r in rows)


# ---------------------------------------------------------------------------
# Manifest contribution lookup
# ---------------------------------------------------------------------------


class TestContributionInfo:
    def test_lookup_returns_normalized_preset_declaration(
        self, spec_kit_project: Path
    ):
        install_preset(
            spec_kit_project,
            "normalized-preset",
            {
                "templates": [
                    {
                        "type": "template",
                        "name": "normalized-template",
                        "strategy": "APPEND",
                    }
                ]
            },
        )

        payload = ArtifactCatalog(spec_kit_project).get_contribution_info(
            "preset:normalized-preset:template:normalized-template"
        )

        assert payload["contribution"]["strategy"] == "append"

    def test_lookup_returns_normalized_extension_declaration(
        self, spec_kit_project: Path
    ):
        extension_dir = (
            spec_kit_project / ".specify" / "extensions" / "normalized-extension"
        )
        extension_dir.mkdir()
        (extension_dir / "commands").mkdir()
        (extension_dir / "commands" / "hello.md").write_text(
            "body", encoding="utf-8"
        )
        (extension_dir / "extension.yml").write_text(
            yaml.safe_dump(
                {
                    "schema_version": "1.0",
                    "extension": {
                        "id": "normalized-extension",
                        "name": "Normalized extension",
                        "version": "1.0.0",
                        "description": "test",
                    },
                    "requires": {"speckit_version": ">=0.2.0"},
                    "provides": {
                        "commands": [
                            {
                                "name": "speckit.hello",
                                "file": "commands/hello.md",
                            }
                        ]
                    },
                }
            ),
            encoding="utf-8",
        )

        payload = ArtifactCatalog(spec_kit_project).get_contribution_info(
            "extension:normalized-extension:command:"
            "speckit.normalized-extension.hello"
        )

        assert payload["contribution"]["name"] == (
            "speckit.normalized-extension.hello"
        )
        assert payload["contribution"]["aliases"] == []

    def test_lookup_omits_missing_contribution_source(
        self, spec_kit_project: Path
    ):
        install_preset(
            spec_kit_project,
            "missing-source",
            {
                "templates": [
                    {
                        "type": "template",
                        "name": "missing-source",
                        "file": "templates/missing.md",
                    }
                ]
            },
        )

        payload = ArtifactCatalog(spec_kit_project).get_contribution_info(
            "preset:missing-source:template:missing-source"
        )

        assert payload["manifestPath"] == (
            ".specify/presets/missing-source/preset.yml"
        )
        assert payload["sourcePath"] is None

    def test_lookup_omits_contribution_source_outside_provider(
        self, spec_kit_project: Path, tmp_path: Path
    ):
        pack = install_preset(
            spec_kit_project,
            "escaping-source",
            {
                "templates": [
                    {
                        "type": "template",
                        "name": "escaping-source",
                        "file": "templates/escape.md",
                    }
                ]
            },
        )
        outside = tmp_path / "outside.md"
        outside.write_text("outside", encoding="utf-8")
        link = pack / "templates" / "escape.md"
        link.parent.mkdir()
        try:
            link.symlink_to(outside)
        except OSError as exc:
            pytest.skip(f"symlink creation unavailable: {exc}")

        payload = ArtifactCatalog(spec_kit_project).get_contribution_info(
            "preset:escaping-source:template:escaping-source"
        )

        assert payload["manifestPath"] == (
            ".specify/presets/escaping-source/preset.yml"
        )
        assert payload["sourcePath"] is None

    def test_lookup_preserves_source_path_through_symlinked_project_root(
        self, spec_kit_project: Path, tmp_path: Path
    ):
        pack = install_preset(
            spec_kit_project,
            "symlinked-project",
            {
                "templates": [
                    {
                        "type": "template",
                        "name": "symlinked-project",
                        "file": "templates/source.md",
                    }
                ]
            },
        )
        source = pack / "templates" / "source.md"
        source.parent.mkdir()
        source.write_text("body", encoding="utf-8")
        linked_project = tmp_path / "linked-project"
        try:
            linked_project.symlink_to(spec_kit_project, target_is_directory=True)
        except OSError as exc:
            pytest.skip(f"directory symlink creation unavailable: {exc}")

        payload = ArtifactCatalog(linked_project).get_contribution_info(
            "preset:symlinked-project:template:symlinked-project"
        )

        assert payload["sourcePath"] == (
            ".specify/presets/symlinked-project/templates/source.md"
        )

    def test_hidden_command_layer_source_path_is_own_pack_file(
        self, spec_kit_project: Path
    ):
        """A hidden (non-active) command row must not report the winner's
        shared materialized agent output as its ``sourcePath``.

        Both presets below register the same command name and the same
        agent skill name, so the tracked materialized output is a single
        shared file. Only the active (winning) row may report that shared
        file; the hidden loser row must report its own installed pack file.
        """
        pack_low = install_preset(
            spec_kit_project,
            "aaa-low-priority-preset",
            {
                "commands": [
                    {
                        "name": "speckit.compliance.plan",
                        "file": "commands/speckit.compliance.plan.md",
                        "description": "Loser",
                    }
                ]
            },
            priority=20,
        )
        (pack_low / "commands").mkdir()
        (pack_low / "commands" / "speckit.compliance.plan.md").write_text(
            "---\ndescription: Loser\n---\nloser body\n", encoding="utf-8"
        )
        PresetRegistry(spec_kit_project / ".specify" / "presets").update(
            "aaa-low-priority-preset",
            {"registered_skills": {"copilot": ["speckit-compliance-plan"]}},
        )

        pack_high = install_preset(
            spec_kit_project,
            "zzz-high-priority-preset",
            {
                "commands": [
                    {
                        "name": "speckit.compliance.plan",
                        "file": "commands/speckit.compliance.plan.md",
                        "description": "Winner",
                    }
                ]
            },
            priority=5,
        )
        (pack_high / "commands").mkdir()
        (pack_high / "commands" / "speckit.compliance.plan.md").write_text(
            "---\ndescription: Winner\n---\nwinner body\n", encoding="utf-8"
        )
        PresetRegistry(spec_kit_project / ".specify" / "presets").update(
            "zzz-high-priority-preset",
            {"registered_skills": {"copilot": ["speckit-compliance-plan"]}},
        )

        skill_file = (
            spec_kit_project
            / ".github"
            / "skills"
            / "speckit-compliance-plan"
            / "SKILL.md"
        )
        skill_file.parent.mkdir(parents=True)
        skill_file.write_text("---\nname: speckit-compliance-plan\n---\n", encoding="utf-8")

        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.compliance.plan")
        stack = info["stack"]
        assert stack[0]["active"] is True
        assert stack[0]["sourcePath"] == ".github/skills/speckit-compliance-plan/SKILL.md"

        hidden_rows = [layer for layer in stack if layer["active"] is False]
        assert hidden_rows
        for row in hidden_rows:
            assert row["sourcePath"] != stack[0]["sourcePath"]
            assert row["sourcePath"] == (
                ".specify/presets/aaa-low-priority-preset/commands/speckit.compliance.plan.md"
            )




# ---------------------------------------------------------------------------
# Preset composition integration β€” active/hidden semantics
# ---------------------------------------------------------------------------


class TestStackComposition:
    @pytest.mark.parametrize(
        ("strategy", "top_content"),
        [
            ("prepend", "top contribution"),
            ("append", "top contribution"),
            ("wrap", "before top\n{CORE_TEMPLATE}\nafter top"),
        ],
    )
    def test_composing_stack_keeps_all_contributing_layers_visible(
        self,
        spec_kit_project: Path,
        strategy: str,
        top_content: str,
    ):
        base_content = PresetResolver(spec_kit_project).resolve_content("spec-template")
        assert base_content is not None

        lower_pack = install_preset(
            spec_kit_project,
            "lower-composer",
            {
                "templates": [
                    {
                        "name": "spec-template",
                        "strategy": "prepend",
                    }
                ]
            },
            priority=10,
        )
        (lower_pack / "templates").mkdir()
        (lower_pack / "templates" / "spec-template.md").write_text(
            "lower contribution", encoding="utf-8"
        )

        top_pack = install_preset(
            spec_kit_project,
            "top-composer",
            {
                "templates": [
                    {
                        "name": "spec-template",
                        "strategy": strategy,
                    }
                ]
            },
            priority=5,
        )
        (top_pack / "templates").mkdir()
        (top_pack / "templates" / "spec-template.md").write_text(
            top_content, encoding="utf-8"
        )

        lower_composed = f"lower contribution\n\n{base_content}"
        if strategy == "prepend":
            expected = f"{top_content}\n\n{lower_composed}"
        elif strategy == "append":
            expected = f"{lower_composed}\n\n{top_content}"
        else:
            expected = top_content.replace("{CORE_TEMPLATE}", lower_composed)

        resolved = PresetResolver(spec_kit_project).resolve_content("spec-template")
        stack = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "template:spec-template"
        )["stack"]

        assert resolved == expected
        assert [row["strategy"] for row in stack] == [
            strategy,
            "prepend",
            "replace",
        ]
        assert [row["active"] for row in stack] == [True, False, False]
        assert [row["hidden"] for row in stack] == [False, False, False]

    def test_preset_command_uses_entry_type(self, spec_kit_project: Path):
        pack = install_preset(
            spec_kit_project,
            "test-command",
            {
                "templates": [
                    {
                        "type": "command",
                        "name": "speckit.constitution",
                        "description": "override",
                    }
                ]
            },
        )
        (pack / "commands").mkdir()
        (pack / "commands" / "speckit.constitution.md").write_text(
            "---\ndescription: override\n---\nbody", encoding="utf-8"
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts()
        assert any(row.id == "command:speckit.constitution" for row in rows)
        assert ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")["kind"] == "command"

    def test_preset_single_segment_command_id_from_list_is_resolvable(
        self, spec_kit_project: Path
    ):
        pack = install_preset(
            spec_kit_project,
            "test-single-command",
            {"commands": [{"name": "specify", "description": "single segment"}]},
        )
        (pack / "commands").mkdir()
        (pack / "commands" / "specify.md").write_text(
            "---\ndescription: single segment\n---\nbody", encoding="utf-8"
        )

        catalog = ArtifactCatalog(spec_kit_project)
        ids = {row.id for row in catalog.list_artifacts()}

        assert "command:specify" in ids
        info = catalog.get_artifact_info("command:specify")
        assert info["id"] == "command:specify"
        assert catalog.get_artifact_info("specify", kind="command")["id"] == "command:specify"

    def test_append_only_candidate_without_base_is_not_listed(
        self, spec_kit_project: Path
    ):
        pack = install_preset(
            spec_kit_project,
            "append-only",
            {
                "templates": [
                    {
                        "type": "template",
                        "name": "append-only-template",
                        "strategy": "append",
                    }
                ]
            },
        )
        (pack / "templates").mkdir()
        (pack / "templates" / "append-only-template.md").write_text(
            "append", encoding="utf-8"
        )

        catalog = ArtifactCatalog(spec_kit_project)

        assert "template:append-only-template" not in {
            row.id for row in catalog.list_artifacts()
        }
        with pytest.raises(ArtifactNotFoundError):
            catalog.get_artifact_info("append-only-template", kind="template")

    def test_preset_replace_hides_core(self, spec_kit_project: Path):
        # Install a preset that replaces the constitution command.
        pack = install_preset(
            spec_kit_project,
            "test-replace",
            {"commands": [{"name": "speckit.constitution", "description": "override"}]},
        )
        (pack / "commands").mkdir()
        (pack / "commands" / "speckit.constitution.md").write_text(
            "---\ndescription: override\n---\nbody", encoding="utf-8"
        )

        info = ArtifactCatalog(spec_kit_project).get_artifact_info("speckit.constitution")
        stack = info["stack"]
        assert stack[0]["active"] is True
        assert stack[0]["hidden"] is False
        # If a lower built-in layer exists it must be hidden.
        built_in_rows = [layer for layer in stack if layer["layer"] is None]
        for row in built_in_rows:
            assert row["hidden"] is True


# ---------------------------------------------------------------------------
# Convention-based discovery β€” extensions without a manifest, project overrides
# ---------------------------------------------------------------------------


class TestConventionDiscovery:
    def test_unregistered_extension_template_without_manifest(self, spec_kit_project: Path):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "legacy" / "templates"
        ext_dir.mkdir(parents=True)
        (ext_dir / "legacy-template.md").write_text("body", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        assert any(row.id == "template:legacy-template" for row in catalog.list_artifacts())
        info = catalog.get_artifact_info("legacy-template")
        assert info["stack"][0]["lookupId"] == "extension:legacy:template:legacy-template"
        assert info["stack"][0]["manifestPath"] is None

    def test_convention_only_extension_does_not_claim_manifest(
        self, spec_kit_project: Path
    ):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "legacy"
        (ext_dir / "templates").mkdir(parents=True)
        (ext_dir / "templates" / "legacy-template.md").write_text(
            "body", encoding="utf-8"
        )
        (ext_dir / "commands").mkdir()
        (ext_dir / "commands" / "other.md").write_text("body", encoding="utf-8")
        (ext_dir / "extension.yml").write_text(
            yaml.safe_dump(
                {
                    "schema_version": "1.0",
                    "extension": {
                        "id": "legacy",
                        "name": "Legacy",
                        "version": "1.0.0",
                        "description": "test",
                        "author": "test",
                        "repository": "https://example.com",
                        "license": "MIT",
                    },
                    "requires": {"speckit_version": ">=0.2.0"},
                    "provides": {
                        "commands": [
                            {
                                "name": "speckit.legacy.other",
                                "file": "commands/other.md",
                            }
                        ]
                    },
                }
            ),
            encoding="utf-8",
        )

        layer = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "legacy-template"
        )["stack"][0]

        assert layer["lookupId"] == "extension:legacy:template:legacy-template"
        assert layer["manifestPath"] is None

    def test_convention_command_and_script_are_listed(self, spec_kit_project: Path):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "legacy"
        (ext_dir / "commands").mkdir(parents=True)
        (ext_dir / "commands" / "speckit.legacy.md").write_text("body", encoding="utf-8")
        (ext_dir / "scripts").mkdir()
        (ext_dir / "scripts" / "legacy-script.sh").write_text("#!/bin/sh\n", encoding="utf-8")

        ids = {row.id for row in ArtifactCatalog(spec_kit_project).list_artifacts()}
        assert "command:speckit.legacy" in ids
        assert "script:legacy-script" in ids

    def test_extension_readme_matches_resolver_inventory(self, spec_kit_project: Path):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "legacy"
        ext_dir.mkdir(parents=True)
        (ext_dir / "README.md").write_text("docs", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        artifacts = {row.id: row for row in catalog.list_artifacts()}

        assert "template:README" in artifacts
        assert catalog.get_artifact_info("README")["stack"][0]["sourcePath"] == (
            ".specify/extensions/legacy/README.md"
        )

    def test_disabled_extension_convention_file_is_excluded(self, spec_kit_project: Path):
        extensions_dir = spec_kit_project / ".specify" / "extensions"
        ext_dir = extensions_dir / "legacy" / "templates"
        ext_dir.mkdir(parents=True)
        (ext_dir / "legacy-template.md").write_text("body", encoding="utf-8")
        (extensions_dir / ".registry").write_text(
            json.dumps(
                {
                    "schema_version": "1.0.0",
                    "extensions": {"legacy": {"priority": 10, "enabled": False}},
                }
            ),
            encoding="utf-8",
        )

        ids = {row.id for row in ArtifactCatalog(spec_kit_project).list_artifacts()}
        assert "template:legacy-template" not in ids

    def test_project_override_only_artifact_is_listed(self, spec_kit_project: Path):
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        (overrides / "scripts").mkdir(parents=True)
        (overrides / "local-template.md").write_text("body", encoding="utf-8")
        (overrides / "scripts" / "local-script.sh").write_text("#!/bin/sh\n", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        ids = {row.id for row in catalog.list_artifacts()}
        assert "command:local-template" in ids
        assert "template:local-template" in ids
        assert "script:local-script" in ids
        for kind in ("command", "template"):
            info = catalog.get_artifact_info(f"{kind}:local-template")
            assert info["stack"][0]["layer"] == "project"
        with pytest.raises(AmbiguousArtifactError):
            catalog.get_artifact_info("local-template")

    def test_project_override_reports_its_own_description(self, spec_kit_project: Path):
        """An override's frontmatter/comment metadata wins over the hidden layer."""
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir(parents=True)
        (commands_dir / "speckit.constitution.md").write_text(
            "---\ndescription: Core description\n---\n", encoding="utf-8"
        )
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        (overrides / "scripts").mkdir(parents=True)
        (overrides / "speckit.constitution.md").write_text(
            "---\ndescription: Override description\n---\n", encoding="utf-8"
        )
        (overrides / "scripts" / "local-script.sh").write_text(
            "#!/bin/sh\n# Override script description\n", encoding="utf-8"
        )

        catalog = ArtifactCatalog(spec_kit_project)
        rows = {row.id: row.description for row in catalog.list_artifacts()}
        assert rows["command:speckit.constitution"] == "Override description"
        assert rows["script:local-script"] == "Override script description"

    def test_project_override_without_metadata_falls_back(self, spec_kit_project: Path):
        """A metadata-free override still reports the hidden layer's description."""
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir(parents=True)
        (commands_dir / "speckit.constitution.md").write_text(
            "---\ndescription: Core description\n---\n", encoding="utf-8"
        )
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        overrides.mkdir(parents=True)
        (overrides / "speckit.constitution.md").write_text("body\n", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        rows = {row.id: row.description for row in catalog.list_artifacts()}
        assert rows["command:speckit.constitution"] == "Core description"

    def test_project_override_describes_both_backed_kinds(self, spec_kit_project: Path):
        commands_dir = spec_kit_project / ".specify" / "templates" / "commands"
        commands_dir.mkdir(parents=True)
        (commands_dir / "shared.md").write_text("command\n", encoding="utf-8")
        templates_dir = spec_kit_project / ".specify" / "templates"
        (templates_dir / "shared.md").write_text("template\n", encoding="utf-8")
        overrides = templates_dir / "overrides"
        overrides.mkdir(parents=True)
        (overrides / "shared.md").write_text(
            "---\ndescription: Shared override\n---\n", encoding="utf-8"
        )

        rows = {row.id: row.description for row in ArtifactCatalog(spec_kit_project).list_artifacts()}

        assert rows["command:shared"] == "Shared override"
        assert rows["template:shared"] == "Shared override"

    @pytest.mark.parametrize("name", ["local", "speckit.local"])
    def test_override_only_artifact_exposes_both_resolvable_kinds(
        self, spec_kit_project: Path, name: str
    ):
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        overrides.mkdir(parents=True)
        override = overrides / f"{name}.md"
        override.write_text("body", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        ids = {row.id for row in catalog.list_artifacts()}
        assert f"command:{name}" in ids
        assert f"template:{name}" in ids

        resolver = PresetResolver(spec_kit_project)
        for kind in ("command", "template"):
            layers = resolver.collect_all_layers(name, kind)
            assert layers[0]["path"] == override

            info = catalog.get_artifact_info(f"{kind}:{name}")
            assert info["kind"] == kind
            assert info["stack"][0]["layer"] == "project"

        with pytest.raises(AmbiguousArtifactError):
            catalog.get_artifact_info(name)

    def test_unregistered_preset_template_without_manifest(self, spec_kit_project: Path):
        pack_dir = spec_kit_project / ".specify" / "presets" / "legacy-preset"
        pack_dir.mkdir()
        PresetRegistry(pack_dir.parent).add(
            "legacy-preset", {"priority": 10, "version": "1.0.0"}
        )
        preset_templates_dir = pack_dir / "templates"
        preset_templates_dir.mkdir()
        (preset_templates_dir / "legacy-preset-template.md").write_text(
            "body", encoding="utf-8"
        )

        catalog = ArtifactCatalog(spec_kit_project)
        assert any(
            row.id == "template:legacy-preset-template" for row in catalog.list_artifacts()
        )
        info = catalog.get_artifact_info("legacy-preset-template")
        assert info["stack"][0]["lookupId"] == (
            "preset:legacy-preset:template:legacy-preset-template"
        )

    def test_stale_registry_entry_with_missing_pack_dir_is_skipped(
        self, spec_kit_project: Path
    ):
        pack_dir = spec_kit_project / ".specify" / "presets" / "removed-preset"
        pack_dir.mkdir()
        PresetRegistry(pack_dir.parent).add(
            "removed-preset", {"priority": 10, "version": "1.0.0"}
        )
        shutil.rmtree(pack_dir)

        catalog = ArtifactCatalog(spec_kit_project)
        # Should not raise FileNotFoundError despite the registry entry
        # pointing at a directory that no longer exists on disk; the stale
        # preset contributes no artifacts.
        ids = {row.id for row in catalog.list_artifacts()}
        assert not any("removed-preset" in artifact_id for artifact_id in ids)

    def test_command_backed_override_also_exposes_resolvable_template(
        self, spec_kit_project: Path
    ):
        ext_dir = spec_kit_project / ".specify" / "extensions" / "legacy" / "commands"
        ext_dir.mkdir(parents=True)
        (ext_dir / "speckit.legacy.md").write_text("body", encoding="utf-8")
        overrides = spec_kit_project / ".specify" / "templates" / "overrides"
        overrides.mkdir(parents=True)
        (overrides / "speckit.legacy.md").write_text("override", encoding="utf-8")

        catalog = ArtifactCatalog(spec_kit_project)
        ids = {row.id for row in catalog.list_artifacts()}
        assert "command:speckit.legacy" in ids
        assert "template:speckit.legacy" in ids
        assert catalog.get_artifact_info("command:speckit.legacy")["kind"] == "command"
        assert catalog.get_artifact_info("template:speckit.legacy")["kind"] == "template"
        with pytest.raises(AmbiguousArtifactError):
            catalog.get_artifact_info("speckit.legacy")


class TestPresetDisplayName:
    """`_preset_display_name` delegates to the validated `PresetManifest.name`."""

    _VALID_MANIFEST = """\
schema_version: "1.0"
preset:
  id: pack
  name: Nested Name
  version: "1.0.0"
  description: A test preset
requires:
  speckit_version: ">=1.0.0"
provides:
  templates:
    - type: template
      name: spec-template
      file: spec-template.md
"""

    def test_reads_validated_preset_name(self, tmp_path: Path):
        pack_dir = tmp_path / "pack"
        pack_dir.mkdir()
        (pack_dir / "preset.yml").write_text(self._VALID_MANIFEST, encoding="utf-8")

        assert _preset_display_name(pack_dir, "pack") == "Nested Name"

    def test_falls_back_to_pack_id_when_manifest_fails_validation(self, tmp_path: Path):
        """A legacy flat manifest with no ``preset:`` section fails validation."""
        pack_dir = tmp_path / "pack"
        pack_dir.mkdir()
        (pack_dir / "preset.yml").write_text("id: pack\nname: Flat Name\n", encoding="utf-8")

        assert _preset_display_name(pack_dir, "pack") == "pack"

    def test_falls_back_to_pack_id_without_manifest_file(self, tmp_path: Path):
        pack_dir = tmp_path / "pack"
        pack_dir.mkdir()

        assert _preset_display_name(pack_dir, "pack") == "pack"


# ---------------------------------------------------------------------------
# Hook artifact tests
# ---------------------------------------------------------------------------






class TestHookInventory:
    def test_flat_and_stack_listings_include_the_same_hook(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={"before_specify": [{"command": "speckit.compliance.pre-check"}]},
        )

        catalog = ArtifactCatalog(spec_kit_project)
        flat = next(row for row in catalog.list_artifacts() if row.kind == "hook")
        enriched = next(
            row
            for row in catalog.list_artifacts_with_stack()
            if row["kind"] == "hook"
        )

        assert isinstance(flat, HookArtifact)
        assert flat.to_json_dict() == {
            key: value for key, value in enriched.items() if key != "stack"
        }

    @pytest.mark.parametrize(
        "hooks",
        [
            {
                "before_specify": [{"command": "speckit.healthy.cmd"}],
                "\ud800": [{"command": "speckit.invalid.cmd"}],
            },
            {
                "before_specify": [
                    {"command": "speckit.healthy.cmd"},
                    {"command": "\ud800"},
                ]
            },
        ],
        ids=["invalid-event", "invalid-command"],
    )
    def test_invalid_unicode_hook_is_omitted_without_hiding_healthy_hooks(
        self, spec_kit_project: Path, hooks: dict
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "unicode-hooks",
            hooks=hooks,
        )

        catalog = ArtifactCatalog(spec_kit_project)
        flat_hooks = [row for row in catalog.list_artifacts() if row.kind == "hook"]
        enriched_hooks = [
            row for row in catalog.list_artifacts_with_stack() if row["kind"] == "hook"
        ]

        assert [row.targetCommand for row in flat_hooks] == ["speckit.healthy.cmd"]
        assert [row["targetCommand"] for row in enriched_hooks] == [
            "speckit.healthy.cmd"
        ]

    def test_declared_hook_has_artifact_and_stack_shape(
        self, spec_kit_project: Path
    ):
        from specify_cli.artifacts._identifiers import derive_hook_lookup_id

        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={
                "before_specify": [
                    {
                        "command": "speckit.compliance.pre-check",
                        "eventName": "after_plan",
                        "description": "Compliance pre-check",
                        "priority": 5,
                        "optional": False,
                    }
                ]
            },
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")
        entry = row["stack"][0]

        assert row == {
            "id": "hook:before_specify:speckit.compliance.pre-check",
            "kind": "hook",
            "name": "before_specify:speckit.compliance.pre-check",
            "description": "Compliance pre-check",
            "eventName": "before_specify",
            "targetCommand": "speckit.compliance.pre-check",
            "registered": False,
            "stack": [entry],
        }
        assert entry == {
            "id": "hook:before_specify:speckit.compliance.pre-check",
            "layer": "extension",
            "sourceId": "compliance",
            "presetId": None,
            "presetName": None,
            "strategy": "additive",
            "active": False,
            "hidden": False,
            "manifestPath": ".specify/extensions/compliance/extension.yml",
            "lookupId": derive_hook_lookup_id(
                "extension",
                "compliance",
                "before_specify",
                "speckit.compliance.pre-check",
            ),
            "sourcePath": None,
            "priority": 5,
            "optional": False,
        }
        contribution = ArtifactCatalog(spec_kit_project).get_contribution_info(
            entry["lookupId"]
        )
        assert contribution["id"] == entry["lookupId"]
        assert contribution["kind"] == "hook"
        assert contribution["contribution"] == {
            "eventName": "before_specify",
            "command": "speckit.compliance.pre-check",
            "description": "Compliance pre-check",
            "priority": 5,
            "optional": False,
        }

    def test_hook_lookup_targets_installed_provider_with_shared_manifest_id(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "a-copy",
            manifest_id="shared-hooks",
            hooks={"after_plan": [{"command": "unrelated.cmd"}]},
        )
        second = install_extension_with_hooks(
            spec_kit_project,
            "b-copy",
            manifest_id="shared-hooks",
            hooks={
                "before_specify": [
                    {
                        "command": "target.cmd",
                        "description": "Second manifest target",
                    }
                ]
            },
        )

        catalog = ArtifactCatalog(spec_kit_project)
        hook = next(
            row
            for row in catalog.list_artifacts_with_stack()
            if row["kind"] == "hook" and row["targetCommand"] == "target.cmd"
        )
        contribution = catalog.get_contribution_info(
            hook["stack"][0]["lookupId"]
        )

        assert contribution["manifestPath"] == (
            second.relative_to(spec_kit_project).as_posix() + "/extension.yml"
        )
        assert contribution["contribution"]["eventName"] == "before_specify"
        assert contribution["contribution"]["command"] == "target.cmd"

    def test_same_manifest_id_hook_layers_have_distinct_lookup_ids(
        self, spec_kit_project: Path
    ):
        for installed_id, description in (
            ("a-copy", "First hook"),
            ("b-copy", "Second hook"),
        ):
            install_extension_with_hooks(
                spec_kit_project,
                installed_id,
                manifest_id="shared-hooks",
                hooks={
                    "before_specify": [
                        {
                            "command": "target.cmd",
                            "description": description,
                        }
                    ]
                },
            )

        catalog = ArtifactCatalog(spec_kit_project)
        hook = next(
            row
            for row in catalog.list_artifacts_with_stack()
            if row["kind"] == "hook" and row["targetCommand"] == "target.cmd"
        )

        assert [entry["sourceId"] for entry in hook["stack"]] == [
            "a-copy",
            "b-copy",
        ]
        assert [entry["lookupId"] for entry in hook["stack"]] == [
            "extension:a-copy:hook:before_specify:target.cmd",
            "extension:b-copy:hook:before_specify:target.cmd",
        ]
        resolved = [
            catalog.get_contribution_info(entry["lookupId"])
            for entry in hook["stack"]
        ]
        assert [
            contribution["contribution"]["description"]
            for contribution in resolved
        ] == ["First hook", "Second hook"]
        assert [contribution["manifestPath"] for contribution in resolved] == [
            ".specify/extensions/a-copy/extension.yml",
            ".specify/extensions/b-copy/extension.yml",
        ]

    def test_duplicate_declarations_are_additive_and_priority_sorted(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "ext-a",
            hooks={"before_specify": [{"command": "shared.cmd", "priority": 10}]},
        )
        install_extension_with_hooks(
            spec_kit_project,
            "ext-b",
            hooks={"before_specify": [{"command": "shared.cmd", "priority": 3}]},
        )
        write_hook_binding(
            spec_kit_project,
            "before_specify",
            [
                {"extension": "ext-a", "command": "shared.cmd", "enabled": True},
                {"extension": "ext-b", "command": "shared.cmd", "enabled": True},
            ],
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")

        assert [entry["sourceId"] for entry in row["stack"]] == ["ext-b", "ext-a"]
        assert all(entry["strategy"] == "additive" for entry in row["stack"])
        assert all(entry["active"] is True for entry in row["stack"])
        assert row["registered"] is True

    def test_equal_priorities_preserve_deterministic_resolver_order(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "ext-a",
            hooks={"before_specify": [{"command": "shared.cmd", "priority": 5}]},
            priority=5,
        )
        install_extension_with_hooks(
            spec_kit_project,
            "ext-b",
            hooks={"before_specify": [{"command": "shared.cmd", "priority": 5}]},
            priority=10,
        )

        catalog = ArtifactCatalog(spec_kit_project)
        observed_orders = []
        for _ in range(2):
            rows = catalog.list_artifacts_with_stack()
            row = next(item for item in rows if item["kind"] == "hook")
            observed_orders.append(
                [entry["sourceId"] for entry in row["stack"]]
            )

        assert observed_orders == [["ext-a", "ext-b"], ["ext-a", "ext-b"]]

    def test_duplicate_declarations_within_extension_use_last_value(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "ext",
            hooks={
                "before_specify": [
                    {
                        "command": "shared.cmd",
                        "description": "Old declaration",
                        "priority": 20,
                        "optional": True,
                    },
                    {
                        "command": "shared.cmd",
                        "description": "Current declaration",
                        "priority": 4,
                        "optional": False,
                    },
                ]
            },
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")

        assert row["description"] == "Current declaration"
        assert len(row["stack"]) == 1
        assert row["stack"][0]["priority"] == 4
        assert row["stack"][0]["optional"] is False

    def test_disabled_extension_contributions_are_excluded(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "disabled",
            hooks={"before_specify": [{"command": "disabled.cmd"}]},
            enabled=False,
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        assert all(row["kind"] != "hook" for row in rows)

    @pytest.mark.parametrize("registered", [True, False])
    def test_malformed_manifest_is_omitted_without_hiding_healthy_hooks(
        self, spec_kit_project: Path, registered: bool
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "healthy",
            hooks={"before_specify": [{"command": "speckit.healthy.cmd"}]},
        )
        broken_dir = (
            spec_kit_project / ".specify" / "extensions" / "broken"
        )
        broken_dir.mkdir()
        (broken_dir / "extension.yml").write_text(
            "schema_version: [\n", encoding="utf-8"
        )
        if registered:
            ExtensionRegistry(
                spec_kit_project / ".specify" / "extensions"
            ).add(
                "broken",
                {"version": "1.0.0", "enabled": True, "priority": 10},
            )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        hook_rows = [row for row in rows if row["kind"] == "hook"]

        assert [row["targetCommand"] for row in hook_rows] == [
            "speckit.healthy.cmd"
        ]
        assert hook_rows[0]["stack"][0]["sourceId"] == "healthy"

    def test_hooks_never_use_builtin_layer(self, spec_kit_project: Path):
        install_extension_with_hooks(
            spec_kit_project,
            "ext",
            hooks={"before_specify": [{"command": "cmd.x"}]},
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        hook_entries = [
            entry
            for row in rows
            if row["kind"] == "hook"
            for entry in row["stack"]
        ]
        assert hook_entries
        assert {entry["layer"] for entry in hook_entries} <= {
            "preset",
            "extension",
        }


class TestHookRegistration:
    @pytest.mark.parametrize(
        ("binding", "expected"),
        [
            (
                {
                    "extension": "compliance",
                    "command": "speckit.compliance.pre-check",
                    "enabled": True,
                },
                True,
            ),
            (
                {
                    "extension": "compliance",
                    "command": "speckit.compliance.pre-check",
                    "enabled": False,
                },
                False,
            ),
            ({"extension": "compliance", "enabled": True}, False),
        ],
    )
    def test_registration_matches_runtime_binding(
        self,
        spec_kit_project: Path,
        binding: dict,
        expected: bool,
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={"before_specify": [{"command": "speckit.compliance.pre-check"}]},
        )
        write_hook_binding(spec_kit_project, "before_specify", [binding])

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")

        assert row["registered"] is expected
        assert row["stack"][0]["active"] is expected

    def test_binding_only_activates_matching_command(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={
                "before_specify": [
                    {"command": "speckit.compliance.pre-check"},
                    {"command": "speckit.compliance.audit"},
                ]
            },
        )
        write_hook_binding(
            spec_kit_project,
            "before_specify",
            [
                {
                    "extension": "compliance",
                    "command": "speckit.compliance.pre-check",
                    "enabled": True,
                }
            ],
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        hooks = {
            row["targetCommand"]: row for row in rows if row["kind"] == "hook"
        }

        assert hooks["speckit.compliance.pre-check"]["registered"] is True
        assert hooks["speckit.compliance.audit"]["registered"] is False

    def test_duplicate_contributors_activate_independently(
        self, spec_kit_project: Path
    ):
        for extension_id in ("ext-a", "ext-b"):
            install_extension_with_hooks(
                spec_kit_project,
                extension_id,
                hooks={"before_specify": [{"command": "shared.cmd"}]},
            )
        write_hook_binding(
            spec_kit_project,
            "before_specify",
            [
                {
                    "extension": "ext-b",
                    "command": "shared.cmd",
                    "enabled": True,
                }
            ],
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")
        active_by_source = {
            entry["sourceId"]: entry["active"] for entry in row["stack"]
        }

        assert active_by_source == {"ext-a": False, "ext-b": True}
        assert row["registered"] is True

    def test_renamed_installation_uses_manifest_id_for_runtime_activation(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "renamed-installation",
            manifest_id="runtime-id",
            hooks={
                "before_specify": [
                    {"command": "speckit.runtime-id.pre-check"}
                ]
            },
        )
        write_hook_binding(
            spec_kit_project,
            "before_specify",
            [
                {
                    "extension": "runtime-id",
                    "command": "speckit.runtime-id.pre-check",
                    "enabled": True,
                }
            ],
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")
        entry = row["stack"][0]

        assert entry["sourceId"] == "renamed-installation"
        assert entry["lookupId"] == (
            "extension:renamed-installation:hook:"
            "before_specify:speckit.runtime-id.pre-check"
        )
        assert entry["active"] is True
        assert row["registered"] is True

    def test_invalid_runtime_config_degrades_to_unregistered(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={"before_specify": [{"command": "speckit.compliance.pre-check"}]},
        )
        (spec_kit_project / ".specify" / "extensions.yml").write_text(
            "this is not: valid: yaml: [\n", encoding="utf-8"
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")
        assert row["registered"] is False


class TestHookInfo:
    def test_hook_shorthand_round_trips(self, spec_kit_project: Path):
        install_extension_with_hooks(
            spec_kit_project,
            "compliance",
            hooks={"before_specify": [{"command": "speckit.compliance.pre-check"}]},
        )

        payload = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "hook:before_specify:speckit.compliance.pre-check"
        )

        assert payload["id"] == "hook:before_specify:speckit.compliance.pre-check"
        assert payload["eventName"] == "before_specify"
        assert payload["targetCommand"] == "speckit.compliance.pre-check"

    def test_colon_containing_values_round_trip_through_encoded_id(
        self, spec_kit_project: Path
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "ext",
            hooks={
                "custom:after": [
                    {
                        "command": "/skill:speckit-test-ext-hello",
                        "description": "Colon-compatible hook",
                    }
                ]
            },
        )

        rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
        row = next(item for item in rows if item["kind"] == "hook")

        assert (
            row["id"]
            == "hook:custom%3Aafter:%2Fskill%3Aspeckit-test-ext-hello"
        )
        assert row["name"] == (
            "custom%3Aafter:%2Fskill%3Aspeckit-test-ext-hello"
        )
        assert row["eventName"] == "custom:after"
        assert row["targetCommand"] == "/skill:speckit-test-ext-hello"
        assert row["stack"][0]["lookupId"] == (
            "extension:ext:hook:custom%3Aafter:"
            "%2Fskill%3Aspeckit-test-ext-hello"
        )

        info = ArtifactCatalog(spec_kit_project).get_artifact_info(row["id"])
        assert info == row
        contribution = ArtifactCatalog(spec_kit_project).get_contribution_info(
            row["stack"][0]["lookupId"]
        )
        assert contribution["contribution"]["eventName"] == "custom:after"
        assert (
            contribution["contribution"]["command"]
            == "/skill:speckit-test-ext-hello"
        )

    def test_kind_hint_resolves_hook_name(self, spec_kit_project: Path):
        install_extension_with_hooks(
            spec_kit_project,
            "ext",
            hooks={"after_plan": [{"command": "cmd.x"}]},
        )

        payload = ArtifactCatalog(spec_kit_project).get_artifact_info(
            "after_plan:cmd.x", kind="hook"
        )
        assert payload["kind"] == "hook"

    @pytest.mark.parametrize(
        "event_name", ["command", "template", "script", "hook"]
    )
    def test_kind_hint_disambiguates_reserved_event_names(
        self, spec_kit_project: Path, event_name: str
    ):
        install_extension_with_hooks(
            spec_kit_project,
            "ext",
            hooks={event_name: [{"command": "cmd.x"}]},
        )

        catalog = ArtifactCatalog(spec_kit_project)
        row = next(
            item
            for item in catalog.list_artifacts_with_stack()
            if item["kind"] == "hook"
        )

        assert catalog.get_artifact_info(row["id"]) == row
        assert catalog.get_artifact_info(row["name"], kind="hook") == row
        assert row["eventName"] == event_name

    def test_unknown_hook_uses_unknown_artifact_error(
        self, spec_kit_project: Path
    ):
        with pytest.raises(ArtifactNotFoundError, match="unknown artifact"):
            ArtifactCatalog(spec_kit_project).get_artifact_info(
                "hook:nope:missing.cmd"
            )




def test_existing_artifact_shapes_do_not_gain_hook_fields(
    spec_kit_project: Path,
):
    rows = ArtifactCatalog(spec_kit_project).list_artifacts_with_stack()
    for row in rows:
        if row["kind"] == "hook":
            continue
        assert "eventName" not in row
        assert "targetCommand" not in row
        assert "registered" not in row


def test_module_imports():
    assert ArtifactCatalog is not None