π« Toolkit to help you get started with SDD or any other process!
"""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