π« Toolkit to help you get started with SDD or any other process!
feat: add artifact-owned contribution lookup (#4550)
nicolehaugend848fb4e18f4
diff --git a/docs/reference/artifacts.md b/docs/reference/artifacts.mdindex 2832f2452..35bbec9f4 100644--- a/docs/reference/artifacts.md+++ b/docs/reference/artifacts.md@@ -4,7 +4,7 @@ An **artifact** is any command, template, script, or hook Spec Kit exposes in aThe `specify artifact` command group is the read-only introspection surface for that inventory. `specify preset resolve <name>` answers "which file wins for this preset-managed name?"; `specify artifact` answers "what exists at all, and what is the full composition stack behind it?" β including built-in artifacts that no preset touches.-Both subcommands currently require `--json`. Omitting it exits with code `2` and prints a usage message on stderr; no stdout is produced. Text rendering is deliberately deferred so the JSON shapes below are the only contract, and adding a default text renderer later stays a non-breaking, additive change.+All subcommands currently require `--json`. Omitting it exits with code `2` and prints a usage message on stderr; no stdout is produced. Text rendering is deliberately deferred so the JSON shapes below are the only contract, and adding a default text renderer later stays a non-breaking, additive change.## List Artifacts@@ -135,7 +135,7 @@ For command, template, and script artifacts, `stack` is ordered by resolution pr| -------------- | -------------------------------------------------------------------------------- || `id` | `{kind}:{name}` β the source-agnostic round-trip key, identical on every row of the same artifact's stack || `layer` | `project`, `preset`, or `extension`; `null` for built-in layers |-| `sourceId` | Source component of `lookupId`, or `null` when the layer has no provenance |+| `sourceId` | Installed preset or extension ID used by the resolver, or `null` when the layer has no provenance || `presetId` | Preset pack directory id; `null` on built-in, `project`, and `extension` rows || `presetName` | Preset display name when its manifest declares one, else the pack id; `null` when `presetId` is `null` || `strategy` | `replace`, `wrap`, `prepend`, `append`, or `additive` |@@ -147,7 +147,44 @@ For command, template, and script artifacts, `stack` is ordered by resolution pr`active` and `hidden` are independent labels, not opposites. For command, template, and script artifacts, `active` identifies the highest-precedence layer selected by the existing Spec Kit layer-resolution order; it does not validate that the layer content can be read or composed. This preserves the diagnostic behavior of `specify preset resolve`, which reports the discovered layer chain even when content composition later produces a warning. Composing strategies (`wrap`, `prepend`, `append`) keep lower layers in the composed output, so an inactive layer is not necessarily hidden: only layers below the first `replace` layer are marked `hidden`. Built-in rows have no provenance: `layer`, `sourceId`, and `lookupId` are `null` β but `id` is always populated, even on built-in rows. `id` is the round-trip key: `specify artifact info` accepts it as input (for example, `specify artifact info command:speckit.specify --json`), and it resolves the same artifact whether the caller passes the bare name or the `id`.-Lookup IDs are derived by the artifact command from the resolved layer and its existing preset or extension manifest. Manifest-declared layers use the manifest's `id`; convention-only layers use the installed preset or extension directory id. Project-local overrides carry a synthetic `project:_:{kind}:{name}` ID, while built-in layers have no `lookupId`. These values are artifact-stack provenance, not the round-trip key β use `id` for that. `sourcePath` is populated only when the layer maps to a concrete installed preset/extension file or a tracked agent materialization; core, project-override, and other synthetic rows report `null`.+Here, **provenance** means the origin of one artifact layer: the installed+preset or extension that supplied it, the manifest that declared it, and the+concrete file that backs it. Lookup IDs use the installed preset or extension+ID, matching the identity and ordering used by the existing resolver. The+installed ID is the registry/directory name and may differ from the logical+`id` declared inside the manifest. Using the installed ID keeps separate+installed directories distinct even when their manifests declare the same+logical ID.++Project-local overrides carry a synthetic `project:_:{kind}:{name}` ID, while+built-in layers have no `lookupId`. These values identify artifact-stack+provenance; they are not the artifact round-trip key β use `id` with+`artifact info` for that. `manifestPath` identifies the declaring manifest,+and `sourcePath` identifies the concrete file backing the layer when one+exists. Core, project-override, and other synthetic rows may report+`sourcePath: null`.++## Contribution Lookup++```bash+specify artifact lookup <lookupId> --json+```++Resolves a manifest-backed stack `lookupId` to the validated preset or extension+declaration that Spec Kit uses. The returned declaration reflects normal+manifest processing, including canonical extension command names, injected+defaults such as empty alias lists, and lowercase preset strategies. It is not+a verbatim representation of the authored YAML.++This keeps cross-reference behavior inside the artifact command: preset and+extension commands, manifests, and resolver return shapes are unchanged.++The response includes the stable lookup ID, provider coordinates, manifest and+source paths, and the effective declaration under `contribution`.+Convention-only contributions and project overrides have no originating+manifest declaration, so lookup returns+`{"error": "unknown contribution <lookupId>"}` with exit code `1`. Built-in+rows never have a `lookupId`.### Hook artifacts@@ -184,7 +221,7 @@ For hooks, `active` reports registration state from `.specify/extensions.yml`, nDeclared-but-unregistered hooks remain visible when their extension is included by the normal resolver. Registry-disabled extensions are excluded entirely, consistently with their other contributions. Invalid individual extension manifests are also omitted by the existing resolver and remain diagnosable through extension inspection and validation commands.-Hook lookup IDs use the artifact-private `{layer}:{sourceId}:hook:{encodedEventName}:{encodedTargetCommand}` grammar. Hook provenance is restricted to `preset` and `extension` layers; hooks never receive a built-in/core layer. The current manifest API exposes extension hook declarations, so current rows use the `extension` layer. The `preset` layer remains reserved by the hook identifier grammar for preset-provided hooks without requiring artifact IDs to be added to preset or extension manifest APIs.+Hook lookup IDs use the artifact-private `{layer}:{sourceId}:hook:{encodedEventName}:{encodedTargetCommand}` grammar, where `sourceId` is the installed provider ID. Hook provenance is restricted to `preset` and `extension` layers; hooks never receive a built-in/core layer. The current manifest API exposes extension hook declarations, so current rows use the `extension` layer. The `preset` layer remains reserved by the hook identifier grammar for preset-provided hooks without requiring artifact IDs to be added to preset or extension manifest APIs.## JSON Errorsdiff --git a/src/specify_cli/artifacts/__init__.py b/src/specify_cli/artifacts/__init__.pyindex d704c3a02..8b1790b76 100644--- a/src/specify_cli/artifacts/__init__.py+++ b/src/specify_cli/artifacts/__init__.py@@ -8,6 +8,7 @@ from .models import (ArtifactKind,ArtifactNotFoundError,ArtifactResolutionError,+ ContributionNotFoundError,HookArtifact,HookLayerName,HookStackEntry,@@ -25,6 +26,7 @@ __all__ = ["ArtifactKind","ArtifactNotFoundError","ArtifactResolutionError",+ "ContributionNotFoundError","HookArtifact","HookLayerName","HookStackEntry",diff --git a/src/specify_cli/artifacts/_commands.py b/src/specify_cli/artifacts/_commands.pyindex 986ca2edf..2c129df03 100644--- a/src/specify_cli/artifacts/_commands.py+++ b/src/specify_cli/artifacts/_commands.py@@ -158,6 +158,44 @@ def artifact_info(sys.stdout.write("\n")+@artifact_app.command("lookup")+def artifact_lookup(+ lookup_id: str = typer.Argument(..., help="Contribution lookupId from an artifact stack."),+ json_flag: bool = typer.Option(+ False,+ "--json",+ help="Emit the validated manifest contribution used by Spec Kit as JSON.",+ ),+) -> None:+ """Resolve a stack lookupId to its effective preset or extension contribution."""+ _require_json_flag(json_flag)+ try:+ root = _resolve_project_root()+ payload = ArtifactCatalog(root).get_contribution_info(lookup_id)+ except ArtifactError as exc:+ _emit_error_and_exit(exc)+ return # pragma: no cover+ except (OSError, PresetError):+ _emit_error_and_exit(ArtifactResolutionError())+ return # pragma: no cover++ try:+ rendered = json.dumps(+ payload,+ indent=2,+ sort_keys=True,+ ensure_ascii=False,+ allow_nan=False,+ )+ rendered.encode("utf-8")+ except (TypeError, ValueError, UnicodeEncodeError):+ _emit_error_and_exit(ArtifactResolutionError())+ return # pragma: no cover++ sys.stdout.write(rendered)+ sys.stdout.write("\n")++def register(app: typer.Typer) -> None:"""Attach the artifact command group to the root Typer app."""app.add_typer(artifact_app, name="artifact")diff --git a/src/specify_cli/artifacts/_identifiers.py b/src/specify_cli/artifacts/_identifiers.pyindex 7b5cfb644..0da6499ac 100644--- a/src/specify_cli/artifacts/_identifiers.py+++ b/src/specify_cli/artifacts/_identifiers.py@@ -99,6 +99,31 @@ def parse_hook_artifact_name(name: str) -> tuple[str, str]:)+def parse_lookup_id(value: str) -> tuple[str, str, str, str]:+ """Parse a contribution lookup ID into layer, source, kind, and name."""+ if not isinstance(value, str):+ raise IdentifierComponentError("Invalid lookupId")+ parts = value.split(":")+ if len(parts) == 4:+ layer, source_id, kind, name = parts+ derive_lookup_id(layer, source_id, kind, name)+ return layer, source_id, kind, name+ if len(parts) == 5 and parts[2] == "hook":+ layer, source_id, kind, encoded_event, encoded_command = parts+ if layer not in _HOOK_LAYERS or source_id == "_":+ raise IdentifierComponentError("Invalid hook lookupId")+ event_name, command = parse_hook_artifact_name(+ f"{encoded_event}:{encoded_command}"+ )+ if (+ derive_hook_lookup_id(layer, source_id, event_name, command)+ != value+ ):+ raise IdentifierComponentError("Invalid hook lookupId")+ return layer, source_id, kind, f"{encoded_event}:{encoded_command}"+ raise IdentifierComponentError("Invalid lookupId")++def _encode_hook_component(value: Any, field_label: str) -> str:"""Encode one hook ID component without narrowing manifest syntax."""if not isinstance(value, str):diff --git a/src/specify_cli/artifacts/catalog.py b/src/specify_cli/artifacts/catalog.pyindex 8180a32e2..d56a3b0a5 100644--- a/src/specify_cli/artifacts/catalog.py+++ b/src/specify_cli/artifacts/catalog.py@@ -25,6 +25,7 @@ from ._identifiers import (derive_hook_public_id,derive_public_id,parse_hook_artifact_name,+ parse_lookup_id,validate_component,)from .models import (@@ -33,6 +34,7 @@ from .models import (ArtifactKind,ArtifactNotFoundError,ArtifactResolutionError,+ ContributionNotFoundError,HookArtifact,HookStackEntry,NotASpecKitProjectError,@@ -405,6 +407,155 @@ class ArtifactCatalog:"stack": [layer.to_json_dict() for layer in stack],}+ def get_contribution_info(self, lookup_id: str) -> dict[str, Any]:+ """Resolve a stack ``lookupId`` to its validated manifest entry."""+ _validate_project(self.project_root)+ _validate_extension_registry(self.project_root)+ try:+ layer, source_id, kind, name = parse_lookup_id(lookup_id)+ except IdentifierComponentError as exc:+ raise ContributionNotFoundError(lookup_id) from exc+ if layer == "project":+ raise ContributionNotFoundError(lookup_id)++ from ..presets import PresetError, PresetResolver++ resolver = PresetResolver(self.project_root)+ try:+ if layer == "preset":+ resolved = self._find_preset_contribution(+ resolver, source_id, kind, name+ )+ else:+ resolved = self._find_extension_contribution(+ resolver, source_id, kind, name+ )+ except (OSError, PresetError) as exc:+ raise ArtifactResolutionError() from exc+ if resolved is None:+ raise ContributionNotFoundError(lookup_id)++ contribution, manifest_path, source_path = resolved+ return {+ "id": lookup_id,+ "layer": layer,+ "sourceId": source_id,+ "kind": kind,+ "name": name,+ "manifestPath": manifest_path,+ "sourcePath": source_path,+ "contribution": contribution,+ }++ def _find_preset_contribution(+ self,+ resolver: Any,+ source_id: str,+ kind: str,+ name: str,+ ) -> tuple[dict[str, Any], str, str | None] | None:+ for pack_id, _metadata in resolver._get_all_presets_by_priority():+ if pack_id != source_id:+ continue+ pack_dir = resolver.presets_dir / pack_id+ manifest = resolver._get_manifest(pack_dir)+ if manifest is None:+ return None+ for entry in manifest.templates:+ if (+ isinstance(entry, dict)+ and entry.get("type") == kind+ and entry.get("name") == name+ ):+ return self._contribution_result(+ entry, pack_dir, manifest.path+ )+ return None++ def _find_extension_contribution(+ self,+ resolver: Any,+ source_id: str,+ kind: str,+ name: str,+ ) -> tuple[dict[str, Any], str, str | None] | None:+ from ..extensions import (+ ExtensionManifest,+ ValidationError,+ coerce_hook_entries,+ )++ for _priority, extension_id, _metadata in resolver._get_all_extensions_by_priority():+ if extension_id != source_id:+ continue+ extension_dir = resolver.extensions_dir / extension_id+ manifest_path = extension_dir / "extension.yml"+ try:+ manifest = ExtensionManifest(manifest_path)+ except (ValidationError, OSError, TypeError, AttributeError):+ return None+ if kind == "hook":+ event_name, command = parse_hook_artifact_name(name)+ matching: dict[str, Any] | None = None+ hook_config = (manifest.hooks or {}).get(event_name)+ for entry in coerce_hook_entries(hook_config):+ if isinstance(entry, dict) and entry.get("command") == command:+ matching = entry+ if matching is None:+ return None+ relative_manifest = _repo_relative_existing_file(+ self.project_root, manifest.path+ )+ if relative_manifest is None:+ raise ArtifactResolutionError()+ return (+ {**matching, "eventName": event_name},+ relative_manifest,+ None,+ )++ entries = {+ "command": manifest.commands,+ "template": manifest.templates,+ "script": manifest.scripts,+ }[kind]+ for entry in entries:+ if isinstance(entry, dict) and entry.get("name") == name:+ return self._contribution_result(+ entry, extension_dir, manifest.path+ )+ return None++ def _contribution_result(+ self,+ entry: dict[str, Any],+ pack_dir: Path,+ manifest_path: Path,+ ) -> tuple[dict[str, Any], str, str | None]:+ relative_manifest = _repo_relative_existing_file(+ self.project_root, manifest_path+ )+ if relative_manifest is None:+ raise ArtifactResolutionError()+ relative_file = entry.get("file")+ source_path = None+ if isinstance(relative_file, str):+ try:+ resolved_pack = pack_dir.resolve()+ candidate = pack_dir / relative_file+ candidate.resolve().relative_to(resolved_pack)+ except (OSError, ValueError):+ pass+ else:+ source_path = _repo_relative_existing_file(+ self.project_root, candidate+ )+ return (+ dict(entry),+ relative_manifest,+ source_path,+ )+def _get_hook_info(self,bare_name: str,@@ -480,7 +631,7 @@ class ArtifactCatalog:)if manifest_path is None:raise ArtifactResolutionError()- source_id = manifest.id+ source_id = extension_idfor event_name, hook_config in (manifest.hooks or {}).items():entries_by_command: dict[@@ -511,6 +662,7 @@ class ArtifactCatalog:"id": public_id,"layer": "extension","sourceId": source_id,+ "runtimeExtensionId": manifest.id,"presetId": None,"presetName": None,"manifestPath": manifest_path,@@ -553,7 +705,8 @@ class ArtifactCatalog:presetName=None,strategy="additive",active=any(- binding.get("extension") == declaration["sourceId"]+ binding.get("extension")+ == declaration["runtimeExtensionId"]and binding.get("command") == commandfor binding in enabled_bindings),diff --git a/src/specify_cli/artifacts/models.py b/src/specify_cli/artifacts/models.pyindex b8125017d..9d012830d 100644--- a/src/specify_cli/artifacts/models.py+++ b/src/specify_cli/artifacts/models.py@@ -139,6 +139,12 @@ class ArtifactNotFoundError(ArtifactError):super().__init__(self.message)+class ContributionNotFoundError(ArtifactError):+ def __init__(self, lookup_id: str) -> None:+ self.message = f"unknown contribution {lookup_id}"+ super().__init__(self.message)++class AmbiguousArtifactError(ArtifactError):def __init__(self, name: str, kinds: Iterable[str]) -> None:kinds_list = sorted(kinds)@@ -165,6 +171,7 @@ __all__ = ["ArtifactKind","ArtifactNotFoundError","ArtifactResolutionError",+ "ContributionNotFoundError","HookArtifact","HookLayerName","HookStackEntry",diff --git a/src/specify_cli/artifacts/resolution.py b/src/specify_cli/artifacts/resolution.pyindex 73625a630..707a1706b 100644--- a/src/specify_cli/artifacts/resolution.py+++ b/src/specify_cli/artifacts/resolution.py@@ -119,17 +119,9 @@ def _layer_provenance(declared = _manifest_entry_for_path(manifest, "extension", extension_dir, kind, name, path)- source_id = (- manifest.id- if declared is not None- and manifest is not None- and isinstance(manifest.id, str)- and manifest.id- else extension_id- )return _LayerProvenance("extension",- source_id,+ extension_id,extension_id,extension_dir,manifest,@@ -148,17 +140,9 @@ def _layer_provenance(declared = _manifest_entry_for_path(manifest, "preset", pack_dir, kind, name, path)- source_id = (- manifest.id- if declared is not None- and manifest is not None- and isinstance(manifest.id, str)- and manifest.id- else pack_id- )return _LayerProvenance("preset",- source_id,+ pack_id,pack_id,pack_dir,manifest,diff --git a/tests/test_artifact_command.py b/tests/test_artifact_command.pyindex 751983f6a..b574dad7b 100644--- a/tests/test_artifact_command.py+++ b/tests/test_artifact_command.py@@ -11,6 +11,7 @@ import jsonimport osimport reimport shutil+from datetime import datefrom pathlib import Pathimport pytest@@ -25,6 +26,7 @@ from specify_cli.artifacts import (ArtifactKind,ArtifactNotFoundError,ArtifactResolutionError,+ ContributionNotFoundError,HookArtifact,NotASpecKitProjectError,)@@ -34,7 +36,8 @@ from specify_cli.presets import PresetRegistry, PresetResolverfrom tests.conftest import install_presetERROR_REGEX = re.compile(- r"^(unknown artifact |ambiguous artifact |artifact resolution failed|not a Spec Kit project)"+ r"^(unknown artifact |unknown contribution |ambiguous artifact |"+ r"artifact resolution failed|not a Spec Kit project)")@@ -321,7 +324,9 @@ class TestListArtifactsContract:assert "disabled-template" not in namesassert "missing-template" not in names- def test_unregistered_extension_manifest_id_wins_for_lookup(self, spec_kit_project: Path):+ 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()@@ -366,20 +371,30 @@ class TestListArtifactsContract:row.id for row in catalog.list_artifacts()}info = catalog.get_artifact_info("speckit.original.hello")- # Artifact projection uses the manifest id without changing the- # resolver's established layer shape.- assert info["stack"][0]["lookupId"] == "extension:original:command: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- # The stack row's manifestPath must still reflect the actual on-disk- # extension directory (``renamed``), not the manifest id embedded in- # ``lookupId``.+ # 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]@@ -388,6 +403,77 @@ class TestListArtifactsContract:"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"@@ -876,6 +962,331 @@ class TestCLI:info = json.loads(info_result.stdout)assert row["stack"] == info["stack"]+ def test_lookup_json_cross_references_manifest_contribution(+ self, spec_kit_project: Path, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.chdir(spec_kit_project)+ pack = install_preset(+ spec_kit_project,+ "lookup-pack",+ {+ "templates": [+ {+ "type": "template",+ "name": "lookup-template",+ "file": "templates/lookup.md",+ "description": "Lookup target",+ }+ ]+ },+ )+ (pack / "templates").mkdir()+ (pack / "templates" / "lookup.md").write_text("body", encoding="utf-8")++ lookup_id = ArtifactCatalog(spec_kit_project).get_artifact_info(+ "template:lookup-template"+ )["stack"][0]["lookupId"]+ result = CliRunner().invoke(+ app, ["artifact", "lookup", lookup_id, "--json"]+ )++ assert result.exit_code == 0, result.stderr+ payload = json.loads(result.stdout)+ assert payload["id"] == lookup_id+ assert payload["contribution"]["description"] == "Lookup target"+ assert payload["sourcePath"] == (+ ".specify/presets/lookup-pack/templates/lookup.md"+ )++ 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_lookup_json_rejects_unknown_contribution(+ self, spec_kit_project: Path, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.chdir(spec_kit_project)+ lookup_id = "extension:missing:command:speckit.missing.command"++ result = CliRunner().invoke(+ app, ["artifact", "lookup", lookup_id, "--json"]+ )++ assert result.exit_code == 1+ assert result.stdout == ""+ assert json.loads(result.stderr) == {+ "error": f"unknown contribution {lookup_id}"+ }++ @pytest.mark.parametrize(+ "manifest_value",+ [+ date(2026, 1, 1),+ float("nan"),+ float("inf"),+ float("-inf"),+ "\ud800",+ ],+ ids=[+ "date",+ "nan",+ "positive-infinity",+ "negative-infinity",+ "unpaired-surrogate",+ ],+ )+ def test_lookup_json_rejects_non_json_manifest_value(+ self,+ spec_kit_project: Path,+ monkeypatch: pytest.MonkeyPatch,+ manifest_value: object,+ ):+ monkeypatch.chdir(spec_kit_project)+ install_preset(+ spec_kit_project,+ "non-json-contribution",+ {+ "templates": [+ {+ "type": "template",+ "name": "non-json-contribution",+ "extra": manifest_value,+ }+ ]+ },+ )++ result = CliRunner().invoke(+ app,+ [+ "artifact",+ "lookup",+ "preset:non-json-contribution:template:non-json-contribution",+ "--json",+ ],+ )++ assert result.exit_code == 1+ assert result.stdout == ""+ assert json.loads(result.stderr) == {+ "error": "artifact resolution failed"+ }++ @pytest.mark.parametrize(+ "lookup_id",+ [+ "invalid:source:command:name",+ "extension:source:invalid:name",+ "extension:source:hook:%FF:command",+ "extension:source:hook:event:%ZZ",+ ],+ )+ def test_lookup_json_rejects_malformed_lookup_id(+ self,+ spec_kit_project: Path,+ monkeypatch: pytest.MonkeyPatch,+ lookup_id: str,+ ):+ monkeypatch.chdir(spec_kit_project)++ result = CliRunner().invoke(+ app, ["artifact", "lookup", lookup_id, "--json"]+ )++ assert result.exit_code == 1+ assert result.stdout == ""+ assert json.loads(result.stderr) == {+ "error": f"unknown contribution {lookup_id}"+ }++ def test_lookup_requires_json_flag(+ self, spec_kit_project: Path, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.chdir(spec_kit_project)+ result = CliRunner().invoke(+ app,+ [+ "artifact",+ "lookup",+ "extension:missing:command:speckit.missing.command",+ ],+ )++ assert result.exit_code == 2+ assert result.stdout == ""++ def test_lookup_validates_project_before_lookup_id(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.chdir(tmp_path)+ result = CliRunner().invoke(+ app,+ ["artifact", "lookup", "project:_:command:local", "--json"],+ )++ assert result.exit_code == 1+ assert result.stdout == ""+ assert json.loads(result.stderr) == {+ "error": "not a Spec Kit project: no .specify/ directory found"+ }+def test_hidden_command_layer_source_path_is_own_pack_file(self, spec_kit_project: Path):@@ -1647,6 +2058,7 @@ def _install_extension_with_hooks(extension_id: str,hooks: dict,*,+ manifest_id: str | None = None,priority: int = 10,enabled: bool = True,) -> Path:@@ -1656,8 +2068,8 @@ def _install_extension_with_hooks(manifest = {"schema_version": "1.0","extension": {- "id": extension_id,- "name": extension_id,+ "id": manifest_id or extension_id,+ "name": manifest_id or extension_id,"version": "1.0.0","description": "Test extension","author": "test",@@ -1768,6 +2180,7 @@ class TestHookInventory:"before_specify": [{"command": "speckit.compliance.pre-check",+ "eventName": "after_plan","description": "Compliance pre-check","priority": 5,"optional": False,@@ -1810,6 +2223,106 @@ class TestHookInventory:"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@@ -2071,6 +2584,43 @@ class TestHookRegistration: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):@@ -2139,6 +2689,14 @@ class TestHookInfo: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(diff --git a/tests/test_artifact_command_parity.py b/tests/test_artifact_command_parity.pyindex 00eeb8561..cdd550eef 100644--- a/tests/test_artifact_command_parity.py+++ b/tests/test_artifact_command_parity.py@@ -62,7 +62,9 @@ class TestResolverParity:assert active["layer"] == "preset"assert active["lookupId"] == "preset:test-manifest-parity:command:speckit.manifest-declared"- def test_preset_manifest_id_mismatch_uses_manifest_id(self, spec_kit_project: Path):+ def test_preset_manifest_id_mismatch_uses_installed_id(+ self, spec_kit_project: Path+ ):pack = install_preset(spec_kit_project,"renamed-preset",@@ -96,22 +98,76 @@ class TestResolverParity:)assert winner == "body-from-renamed-preset"- # Artifact projection uses the manifest's validated id regardless of- # the installed directory name.assert active["lookupId"] == (- "preset:original-preset:command:speckit.preset-renamed.hello"+ "preset:renamed-preset:command:speckit.preset-renamed.hello")+ contribution = catalog.get_contribution_info(active["lookupId"])+ assert contribution["id"] == active["lookupId"]+ assert contribution["layer"] == "preset"+ assert contribution["sourceId"] == "renamed-preset"+ assert contribution["contribution"]["file"] == "commands/actual.md"resolver_layer = PresetResolver(spec_kit_project).collect_all_layers("speckit.preset-renamed.hello", "command")[0]assert "lookupId" not in resolver_layer- # The stack row's presetId / manifestPath must still reflect the- # actual on-disk directory (``renamed-preset``), not the manifest id- # embedded in ``lookupId`` β otherwise the display and manifest path- # would point to a non-existent location.+ assert active["sourceId"] == "renamed-preset"assert active["presetId"] == "renamed-preset"assert active["manifestPath"] == ".specify/presets/renamed-preset/preset.yml"+ def test_duplicate_preset_manifest_ids_resolve_each_installed_layer(+ self, spec_kit_project: Path+ ):+ for installed_id, description in (+ ("a-copy", "First declaration"),+ ("b-copy", "Second declaration"),+ ):+ pack = install_preset(+ spec_kit_project,+ installed_id,+ {+ "commands": [+ {+ "name": "speckit.shared.command",+ "file": "commands/shared.md",+ "description": description,+ }+ ]+ },+ )+ manifest_path = pack / "preset.yml"+ manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))+ manifest["preset"]["id"] = "shared"+ manifest_path.write_text(yaml.safe_dump(manifest), encoding="utf-8")+ (pack / "commands").mkdir()+ (pack / "commands" / "shared.md").write_text(+ description, encoding="utf-8"+ )++ catalog = ArtifactCatalog(spec_kit_project)+ stack = catalog.get_artifact_info("speckit.shared.command")["stack"]+ preset_layers = [layer for layer in stack if layer["layer"] == "preset"]++ assert [layer["sourceId"] for layer in preset_layers] == [+ "a-copy",+ "b-copy",+ ]+ assert [layer["lookupId"] for layer in preset_layers] == [+ "preset:a-copy:command:speckit.shared.command",+ "preset:b-copy:command:speckit.shared.command",+ ]+ resolved = [+ catalog.get_contribution_info(layer["lookupId"])+ for layer in preset_layers+ ]+ assert [+ contribution["contribution"]["description"]+ for contribution in resolved+ ] == ["First declaration", "Second declaration"]+ assert [contribution["manifestPath"] for contribution in resolved] == [+ ".specify/presets/a-copy/preset.yml",+ ".specify/presets/b-copy/preset.yml",+ ]+def test_module_imports():_ = ArtifactCatalog