π« Toolkit to help you get started with SDD or any other process!
"""Artifact inventory and catalog logic. No Typer decorators.
Two public entry points:
* :meth:`ArtifactCatalog.list_artifacts` β flat inventory (id, name, kind, description).
* :meth:`ArtifactCatalog.get_artifact_info` β one row plus its full ordered stack.
Everything else in this module is internal machinery. Callers outside the
artifact command modules should not import the private helpers.
"""
from __future__ import annotations
import re
import shlex
from collections.abc import Iterable
from pathlib import Path, PurePosixPath, PureWindowsPath
from typing import Any, Literal
import yaml
from ._identifiers import (
IdentifierComponentError,
derive_hook_lookup_id,
derive_hook_public_id,
derive_public_id,
parse_hook_artifact_name,
parse_lookup_id,
validate_component,
)
from .models import (
AmbiguousArtifactError,
Artifact,
ArtifactKind,
ArtifactNotFoundError,
ArtifactResolutionError,
ContributionNotFoundError,
HookArtifact,
HookStackEntry,
NotASpecKitProjectError,
)
from .resolution import (
_build_stack,
_layer_provenance,
_repo_relative_existing_file,
)
_TEMPLATE_SUFFIX = ".md"
_SCRIPT_SUFFIX = ".sh"
def _resolve_script_reference(script_root: Path, token: str) -> Path | None:
"""Resolve a command script reference that remains inside *script_root*."""
posix_path = PurePosixPath(token)
windows_path = PureWindowsPath(token)
if posix_path.anchor or windows_path.anchor:
return None
if ".." in posix_path.parts or ".." in windows_path.parts:
return None
relative = Path(token)
if relative.parts and relative.parts[0] == "scripts":
relative = Path(*relative.parts[1:])
if not relative.parts:
return None
try:
resolved_root = script_root.resolve()
candidate = (resolved_root / relative).resolve()
candidate.relative_to(resolved_root)
except (OSError, ValueError):
return None
return candidate if candidate.is_file() else None
def _locate_shared_asset_dir(subdir: str) -> Path | None:
"""Locate a core asset directory without changing shared asset behavior."""
if subdir not in {"commands", "scripts", "templates"}:
return None
from .._assets import _locate_core_pack, _repo_root
core_pack = _locate_core_pack()
bundled = core_pack / subdir if core_pack is not None else None
source = (
_repo_root() / "templates" / "commands"
if subdir == "commands"
else _repo_root() / subdir
)
for candidate in (bundled, source):
if candidate is not None and candidate.is_dir():
return candidate
return None
def _project_core_asset_root(project_root: Path | None, subdir: str) -> Path | None:
"""Return the project-local built-in-tier directory for an asset family, if present."""
if project_root is None:
return None
if subdir not in {"commands", "scripts", "templates"}:
return None # pragma: no cover β internal misuse
from ..presets import PresetResolver # lazy: avoids circular import
candidate = PresetResolver(project_root).templates_dir
if subdir != "templates":
candidate = candidate / subdir
return candidate if candidate.is_dir() else None
def _core_command_logical_name(stem: str) -> str:
return stem if stem.startswith("speckit.") else f"speckit.{stem}"
def _extract_frontmatter_description(text: str) -> str:
"""Return the ``description`` value from YAML frontmatter, else ``""``.
Matches the frontmatter shape used by every core command/template on disk:
a ``---`` fence pair at the top of the file with a YAML mapping between
them. Anything malformed silently yields the empty string β the contract
forbids omission but permits ``""``.
"""
lines = text.splitlines(keepends=True)
if not lines or lines[0].rstrip("\r\n") != "---":
return ""
fence_end = -1
for i, line in enumerate(lines[1:], start=1):
if line.rstrip("\r\n") == "---":
fence_end = i
break
if fence_end == -1:
return ""
try:
data = yaml.safe_load("".join(lines[1:fence_end]))
except yaml.YAMLError:
return ""
if not isinstance(data, dict):
return ""
value = data.get("description", "")
return value if isinstance(value, str) else ""
def _extract_script_description(text: str) -> str:
"""Return the first docstring/comment line of a script, else ``""``.
Supports the three script runtimes Spec Kit ships:
* Python (``.py``): the first line of the module docstring.
* Bash (``.sh``): the first ``#``-prefixed comment line following the
shebang.
* PowerShell (``.ps1``): either the first line of a ``<# ... #>`` block
comment or the first ``#``-prefixed line.
Anything unrecognized yields the empty string.
"""
py_match = re.match(r'^(?:#![^\n]*\n)?\s*(?:"""|\'\'\')(.*?)(?:"""|\'\'\')', text, re.DOTALL)
if py_match:
first = py_match.group(1).strip().splitlines()
if first:
return first[0].strip()
ps_block = re.match(r'^(?:<#\s*(.*?)#>)', text, re.DOTALL)
if ps_block:
first = ps_block.group(1).strip().splitlines()
if first:
return first[0].strip().lstrip(".").strip()
for raw in text.splitlines():
stripped = raw.strip()
if not stripped or stripped.startswith("#!"):
continue
if stripped.startswith("#"):
return stripped.lstrip("#").strip()
break
return ""
def _describe_artifact_file(path: Path, kind: ArtifactKind) -> str:
"""Return the on-disk description for an artifact file, else ``""``.
Routes to the same extractors the inventory uses so a project
override reports its own metadata instead of inheriting the description
of the core/preset layer it hides.
"""
try:
text = path.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
return ""
if kind == "script":
return _extract_script_description(text)
return _extract_frontmatter_description(text)
# ---------------------------------------------------------------------------
# ArtifactCatalog β public faΓ§ade
# ---------------------------------------------------------------------------
def _validate_project(project_root: Path) -> None:
"""Raise NotASpecKitProjectError when ``project_root`` isn't a Spec Kit project.
The two invariants the rest of the module relies on are that
``project_root`` exists and that a ``.specify/`` subdirectory sits under
it. Anything else β missing presets/, missing extensions/, missing
templates/ β is a valid empty-inventory scenario and is not treated as
an error.
"""
if not (project_root / ".specify").is_dir():
raise NotASpecKitProjectError()
def _validate_extension_registry(project_root: Path) -> None:
extensions_dir = project_root / ".specify" / "extensions"
if not extensions_dir.exists():
return
from ..extensions import ExtensionRegistry
if ExtensionRegistry(extensions_dir).is_corrupt():
raise ArtifactResolutionError()
def _resolve_kind_hint(name: str, kind: ArtifactKind | None) -> tuple[str, ArtifactKind | None]:
"""Parse ``kind:name`` shorthand and reconcile it with an explicit ``--kind`` flag.
Returns ``(bare_name, resolved_kind)``. When ``name`` uses the ``kind:name``
grammar and ``kind`` is also set explicitly, the two must agree β a
mismatch is treated as an unknown artifact.
"""
if kind == "hook":
if name.startswith("hook:"):
candidate = name.removeprefix("hook:")
try:
parse_hook_artifact_name(candidate)
except IdentifierComponentError:
pass
else:
return candidate, "hook"
return name, "hook"
if ":" in name:
prefix, _, bare = name.partition(":")
if prefix in ("command", "template", "script"):
resolved: ArtifactKind = prefix # type: ignore[assignment]
if kind is not None and kind != resolved:
raise ArtifactNotFoundError(name)
return bare, resolved
if prefix == "hook":
if kind is not None and kind != "hook":
raise ArtifactNotFoundError(name)
return bare, "hook"
return name, kind
def _validate_artifact_name(name: str, kind: ArtifactKind) -> str:
"""Validate the structural identifier component constraints for ``name``."""
if kind == "hook":
try:
parse_hook_artifact_name(name)
except IdentifierComponentError as exc:
raise ArtifactNotFoundError(name) from exc
return name
try:
return validate_component(name, f"{kind} name")
except IdentifierComponentError as exc:
raise ArtifactNotFoundError(name) from exc
def _is_valid_artifact_name_component(name: Any, kind: ArtifactKind) -> bool:
"""Return ``True`` when ``name`` can appear in an artifact identifier."""
try:
validate_component(name, f"{kind} name")
except IdentifierComponentError:
return False
return True
class ArtifactCatalog:
"""Read-only view over one Spec Kit project's artifact inventory."""
def __init__(self, project_root: Path) -> None:
self.project_root = project_root
# ------------------------------------------------------------------ list
def list_artifacts(self) -> list[Artifact | HookArtifact]:
"""Return every artifact Spec Kit exposes for this project, deduped.
Named artifacts are sorted by kind and name. Hook artifacts follow in
their deterministic event, priority, and declaration order.
Returns an empty list when no artifacts are found rather than raising;
a fresh install with no presets, no extensions, and no built-in assets is
still a valid Spec Kit project.
Skills (``.github/skills/**/SKILL.md``) are intentionally excluded β
they are integration-specific output, not a shipped asset family.
Descriptions are picked from the highest-priority layer that has one,
not the first layer discovered β a built-in command that an active
preset overrides must report the preset's description, and two
competing packs must report the higher-precedence one's. Precedence
is decided by :meth:`PresetResolver.collect_all_layers`'s own
ordering (index 0 = winner), not by enumeration order here.
"""
artifacts, _layers_cache, resolver, _manifest_cache = self._collect_inventory()
hooks, _hook_stack_cache = self._collect_hook_inventory(resolver)
return [*artifacts, *hooks]
def list_artifacts_with_stack(self) -> list[dict[str, Any]]:
"""Return list rows enriched with each artifact's full composition stack."""
artifacts, layers_cache, resolver, manifest_cache = self._collect_inventory()
rows: list[dict[str, Any]] = []
for artifact in artifacts:
stack = _build_stack(
self.project_root,
artifact.kind,
artifact.name,
raw_layers=layers_cache.get((artifact.kind, artifact.name)),
resolver=resolver,
manifest_cache=manifest_cache,
)
row = artifact.to_json_dict()
row["stack"] = [layer.to_json_dict() for layer in stack]
rows.append(row)
hook_rows, hook_stack_cache = self._collect_hook_inventory(resolver)
for hook in hook_rows:
row = hook.to_json_dict()
row["stack"] = [
entry.to_json_dict()
for entry in hook_stack_cache[(hook.eventName, hook.targetCommand)]
]
rows.append(row)
return rows
# ------------------------------------------------------------------ info
def get_artifact_info(
self,
name: str,
kind: ArtifactKind | None = None,
) -> dict[str, Any]:
"""Return the full JSON-ready dict for ``specify artifact info``.
Argument resolution:
* ``name`` accepts the ``kind:name`` grammar as shorthand; when both
the shorthand and ``kind`` are supplied they must agree.
* When neither the shorthand nor ``kind`` narrows the search and
more than one kind matches ``name``, raises
:class:`AmbiguousArtifactError`.
* When no artifact matches, raises :class:`ArtifactNotFoundError`.
"""
bare, resolved_kind = _resolve_kind_hint(name, kind)
if resolved_kind == "hook":
return self._get_hook_info(bare, original_argument=name)
# Project and registry validation happens once, inside
# ``_collect_inventory`` below β the same chokepoint ``list_artifacts``
# uses β so both public methods fail closed identically instead of
# each re-implementing the checks.
inventory, layers_cache, resolver, manifest_cache = self._collect_inventory()
if resolved_kind is None:
matches = [
(artifact.kind, artifact.name)
for artifact in inventory
if artifact.name == bare
]
hook_rows, _hook_stack_cache = self._collect_hook_inventory(resolver)
if any(row.name == bare for row in hook_rows):
matches.append(("hook", bare))
if not matches:
raise ArtifactNotFoundError(name)
if len(matches) > 1:
raise AmbiguousArtifactError(bare, [k for k, _ in matches])
resolved_kind = matches[0][0]
if resolved_kind == "hook":
return self._get_hook_info(
bare, original_argument=name, resolver=resolver
)
validated_name = _validate_artifact_name(bare, resolved_kind)
artifact = next(
(
item
for item in inventory
if item.kind == resolved_kind and item.name == validated_name
),
None,
)
if artifact is None:
raise ArtifactNotFoundError(name)
stack = _build_stack(
self.project_root,
resolved_kind,
validated_name,
raw_layers=layers_cache.get((resolved_kind, validated_name)),
resolver=resolver,
manifest_cache=manifest_cache,
)
if not stack:
raise ArtifactNotFoundError(name)
return {
"id": derive_public_id(resolved_kind, validated_name),
"name": validated_name,
"kind": resolved_kind,
"description": artifact.description,
"stack": [layer.to_json_dict() for layer in stack],
}
def get_contribution_info(self, lookup_id: str) -> dict[str, Any]:
"""Resolve a stack ``lookupId`` to its validated manifest entry."""
_validate_project(self.project_root)
_validate_extension_registry(self.project_root)
try:
layer, source_id, kind, name = parse_lookup_id(lookup_id)
except IdentifierComponentError as exc:
raise ContributionNotFoundError(lookup_id) from exc
if layer == "project":
raise ContributionNotFoundError(lookup_id)
from ..presets import PresetError, PresetResolver
resolver = PresetResolver(self.project_root)
try:
if layer == "preset":
resolved = self._find_preset_contribution(
resolver, source_id, kind, name
)
else:
resolved = self._find_extension_contribution(
resolver, source_id, kind, name
)
except (OSError, PresetError) as exc:
raise ArtifactResolutionError() from exc
if resolved is None:
raise ContributionNotFoundError(lookup_id)
contribution, manifest_path, source_path = resolved
return {
"id": lookup_id,
"layer": layer,
"sourceId": source_id,
"kind": kind,
"name": name,
"manifestPath": manifest_path,
"sourcePath": source_path,
"contribution": contribution,
}
def _find_preset_contribution(
self,
resolver: Any,
source_id: str,
kind: str,
name: str,
) -> tuple[dict[str, Any], str, str | None] | None:
for pack_id, _metadata in resolver._get_all_presets_by_priority():
if pack_id != source_id:
continue
pack_dir = resolver.presets_dir / pack_id
manifest = resolver._get_manifest(pack_dir)
if manifest is None:
return None
for entry in manifest.templates:
if (
isinstance(entry, dict)
and entry.get("type") == kind
and entry.get("name") == name
):
return self._contribution_result(
entry, pack_dir, manifest.path
)
return None
def _find_extension_contribution(
self,
resolver: Any,
source_id: str,
kind: str,
name: str,
) -> tuple[dict[str, Any], str, str | None] | None:
from ..extensions import (
ExtensionManifest,
ValidationError,
coerce_hook_entries,
)
for _priority, extension_id, _metadata in resolver._get_all_extensions_by_priority():
if extension_id != source_id:
continue
extension_dir = resolver.extensions_dir / extension_id
manifest_path = extension_dir / "extension.yml"
try:
manifest = ExtensionManifest(manifest_path)
except (ValidationError, OSError, TypeError, AttributeError):
return None
if kind == "hook":
event_name, command = parse_hook_artifact_name(name)
matching: dict[str, Any] | None = None
hook_config = (manifest.hooks or {}).get(event_name)
for entry in coerce_hook_entries(hook_config):
if isinstance(entry, dict) and entry.get("command") == command:
matching = entry
if matching is None:
return None
relative_manifest = _repo_relative_existing_file(
self.project_root, manifest.path
)
if relative_manifest is None:
raise ArtifactResolutionError()
return (
{**matching, "eventName": event_name},
relative_manifest,
None,
)
entries = {
"command": manifest.commands,
"template": manifest.templates,
"script": manifest.scripts,
}[kind]
for entry in entries:
if isinstance(entry, dict) and entry.get("name") == name:
return self._contribution_result(
entry, extension_dir, manifest.path
)
return None
def _contribution_result(
self,
entry: dict[str, Any],
pack_dir: Path,
manifest_path: Path,
) -> tuple[dict[str, Any], str, str | None]:
relative_manifest = _repo_relative_existing_file(
self.project_root, manifest_path
)
if relative_manifest is None:
raise ArtifactResolutionError()
relative_file = entry.get("file")
source_path = None
if isinstance(relative_file, str):
try:
resolved_pack = pack_dir.resolve()
candidate = pack_dir / relative_file
candidate.resolve().relative_to(resolved_pack)
except (OSError, ValueError):
pass
else:
source_path = _repo_relative_existing_file(
self.project_root, candidate
)
return (
dict(entry),
relative_manifest,
source_path,
)
def _get_hook_info(
self,
bare_name: str,
original_argument: str,
resolver: Any | None = None,
) -> dict[str, Any]:
"""Return one hook row and its additive declaration stack."""
_validate_artifact_name(bare_name, "hook")
event_name, command = parse_hook_artifact_name(bare_name)
hook_rows, stack_cache = self._collect_hook_inventory(resolver)
for row in hook_rows:
if row.eventName != event_name or row.targetCommand != command:
continue
payload = row.to_json_dict()
payload["stack"] = [
entry.to_json_dict()
for entry in stack_cache[(event_name, command)]
]
return payload
raise ArtifactNotFoundError(original_argument)
def _collect_hook_inventory(
self, resolver: Any | None = None
) -> tuple[
list[HookArtifact],
dict[tuple[str, str], list[HookStackEntry]],
]:
"""Project declared hooks and existing runtime bindings into artifact rows."""
from ..extensions import (
DEFAULT_HOOK_PRIORITY,
ExtensionManager,
ExtensionManifest,
HookExecutor,
ValidationError,
coerce_hook_entries,
normalize_priority,
)
from ..presets import PresetError, PresetResolver
if resolver is None:
_validate_project(self.project_root)
_validate_extension_registry(self.project_root)
resolver = PresetResolver(self.project_root)
grouped: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = {}
extension_manager = ExtensionManager(self.project_root)
insertion_index = 0
try:
extensions = resolver._get_all_extensions_by_priority()
for _resolver_priority, extension_id, metadata in extensions:
extension_dir = resolver.extensions_dir / extension_id
if metadata is not None:
manifest = extension_manager.get_extension(extension_id)
else:
manifest_path = extension_dir / "extension.yml"
manifest = None
if manifest_path.is_file():
try:
manifest = ExtensionManifest(manifest_path)
except (
ValidationError,
OSError,
TypeError,
AttributeError,
):
manifest = None
if manifest is None:
continue
manifest_path = _repo_relative_existing_file(
self.project_root, manifest.path
)
if manifest_path is None:
raise ArtifactResolutionError()
source_id = extension_id
for event_name, hook_config in (manifest.hooks or {}).items():
entries_by_command: dict[
str, tuple[dict[str, Any], str, str]
] = {}
for entry in coerce_hook_entries(hook_config):
if not isinstance(entry, dict):
continue
command = entry.get("command")
try:
public_id = derive_hook_public_id(event_name, command)
lookup_id = derive_hook_lookup_id(
"extension", source_id, event_name, command
)
except IdentifierComponentError:
continue
entries_by_command.pop(command, None)
entries_by_command[command] = (
entry,
public_id,
lookup_id,
)
for command, entry_data in entries_by_command.items():
entry, public_id, lookup_id = entry_data
insertion_index += 1
declaration = {
"id": public_id,
"layer": "extension",
"sourceId": source_id,
"runtimeExtensionId": manifest.id,
"presetId": None,
"presetName": None,
"manifestPath": manifest_path,
"lookupId": lookup_id,
"eventName": event_name,
"command": command,
"description": entry.get("description", ""),
"priority": normalize_priority(
entry.get("priority"), DEFAULT_HOOK_PRIORITY
),
"optional": bool(entry.get("optional", True)),
}
grouped.setdefault((event_name, command), []).append(
(insertion_index, declaration)
)
except (OSError, PresetError) as exc:
raise ArtifactResolutionError() from exc
hook_executor = HookExecutor(self.project_root)
enabled_by_event: dict[str, list[dict[str, Any]]] = {}
rows: list[HookArtifact] = []
stack_cache: dict[tuple[str, str], list[HookStackEntry]] = {}
for (event_name, command), declarations in grouped.items():
if event_name not in enabled_by_event:
enabled_by_event[event_name] = hook_executor.get_hooks_for_event(
event_name
)
enabled_bindings = enabled_by_event[event_name]
ordered = sorted(
declarations,
key=lambda item: (item[1]["priority"], item[0]),
)
stack_entries = [
HookStackEntry(
id=declaration["id"],
layer="extension",
sourceId=declaration["sourceId"],
presetId=None,
presetName=None,
strategy="additive",
active=any(
binding.get("extension")
== declaration["runtimeExtensionId"]
and binding.get("command") == command
for binding in enabled_bindings
),
hidden=False,
manifestPath=declaration["manifestPath"],
lookupId=declaration["lookupId"],
sourcePath=None,
priority=declaration["priority"],
optional=declaration["optional"],
)
for _index, declaration in ordered
]
stack_cache[(event_name, command)] = stack_entries
description = next(
(
declaration["description"]
for _index, declaration in ordered
if isinstance(declaration["description"], str)
and declaration["description"]
),
"",
)
public_id = derive_hook_public_id(event_name, command)
rows.append(
HookArtifact(
id=public_id,
name=public_id.removeprefix("hook:"),
kind="hook",
description=description,
eventName=event_name,
targetCommand=command,
registered=any(entry.active for entry in stack_entries),
)
)
rows.sort(
key=lambda row: (
row.eventName,
stack_cache[(row.eventName, row.targetCommand)][0].priority,
)
)
return rows, stack_cache
# -------------------------------------------------------------- internals
def _collect_inventory(
self,
) -> tuple[
list[Artifact],
dict[tuple[ArtifactKind, str], list[dict[str, Any]]],
Any,
dict[Path, Any | None],
]:
_validate_project(self.project_root)
_validate_extension_registry(self.project_root)
from ..presets import ( # lazy: avoids circular import
PresetError,
PresetResolver,
)
resolver = PresetResolver(self.project_root)
layers_cache: dict[tuple[ArtifactKind, str], list[dict[str, Any]]] = {}
core_script_paths = self._selected_core_script_paths()
def _layers_for(kind: ArtifactKind, name: str) -> list[dict[str, Any]]:
key = (kind, name)
if key not in layers_cache:
try:
layers = resolver.collect_all_layers(name, kind)
except (OSError, PresetError) as exc:
raise ArtifactResolutionError() from exc
core_script = core_script_paths.get(name) if kind == "script" else None
if core_script is not None and not any(
layer.get("source") in {"core", "core (bundled)"}
for layer in layers
):
layers.append(
{
"path": core_script,
"source": "core",
"strategy": "replace",
}
)
layers_cache[key] = layers
return layers_cache[key]
def _has_any_replace_layer(layers: list[dict[str, Any]]) -> bool:
return any(layer.get("strategy") == "replace" for layer in layers)
names: set[tuple[ArtifactKind, str]] = set()
try:
for kind, name in self._iter_candidate_artifacts(
resolver, core_script_paths
):
key = (kind, name)
if not _is_valid_artifact_name_component(name, kind):
continue
# Resolve each candidate through Spec Kit's existing single-artifact
# path for behavioral parity; optimize shared manifest reads only if
# typical small extension sets show a measurable inventory cost.
layers = _layers_for(kind, name)
if layers and _has_any_replace_layer(layers):
names.add(key)
except (OSError, PresetError) as exc:
raise ArtifactResolutionError() from exc
artifacts: list[Artifact] = []
manifest_cache: dict[Path, Any | None] = {}
for kind, name in names:
description = ""
for layer in _layers_for(kind, name):
candidate = self._describe_layer(
resolver, layer, kind, name, manifest_cache
)
if candidate:
description = candidate
break
artifacts.append(
Artifact(
id=derive_public_id(kind, name),
name=name,
kind=kind,
description=description,
)
)
kind_order = {"command": 0, "template": 1, "script": 2}
return (
sorted(artifacts, key=lambda a: (kind_order[a.kind], a.name)),
layers_cache,
resolver,
manifest_cache,
)
def _iter_candidate_artifacts(
self,
resolver: Any,
core_script_paths: dict[str, Path],
) -> Iterable[tuple[ArtifactKind, str]]:
"""Yield candidate ``(kind, name)`` pairs from every resolver tier.
Covers the ways a pack can contribute an artifact:
* manifest-declared entries (``preset.yml`` / ``extension.yml``), read
through each manifest class's existing normalized properties, and
* convention-placed extension files (``commands/``, ``templates/``,
``scripts/``) that the resolver picks up even without a manifest.
Presets and extensions are enumerated through the resolver's existing
priority helpers, so the candidate set follows the same install,
enable, and priority rules as resolution. Project overrides and
resolver-compatible core asset paths are included only as candidate
names; :meth:`PresetResolver.collect_all_layers` remains the source of
truth for which candidates are actually present and which layer wins.
Project-local overrides under ``.specify/templates/overrides`` are
included too, so an artifact that exists only as an override is still
listed.
Silent on any manifest that fails to parse β that would already be
surfaced by ``specify preset list`` or ``specify extension list``, and
this command's job is to describe the composed inventory, not to be
the second validation surface.
"""
from ..extensions import ExtensionManager, ExtensionManifest, ValidationError
from ..presets import PresetManager # lazy: avoids circular import
# -- Presets: the registry is authoritative, no unregistered fallback.
preset_manager = PresetManager(self.project_root)
for pack_id, _metadata in resolver._get_all_presets_by_priority():
pack_dir = preset_manager.presets_dir / pack_id
manifest = preset_manager.get_pack(pack_id)
yield from self._iter_pack_candidates(manifest, pack_dir, "preset")
# -- Extensions: use the resolver's own extension enumeration order.
ext_manager = ExtensionManager(self.project_root)
for _priority, ext_id, metadata in resolver._get_all_extensions_by_priority():
ext_dir = resolver.extensions_dir / ext_id
if metadata is not None:
manifest = ext_manager.get_extension(ext_id)
else:
manifest_path = ext_dir / "extension.yml"
manifest = None
if manifest_path.is_file():
try:
manifest = ExtensionManifest(manifest_path)
except (ValidationError, OSError, TypeError, AttributeError):
manifest = None
yield from self._iter_pack_candidates(manifest, ext_dir, "extension")
yield from self._iter_project_override_candidates(resolver)
yield from self._iter_core_candidates(core_script_paths)
@staticmethod
def _iter_pack_candidates(
manifest: Any,
pack_dir: Path,
layer: Literal["preset", "extension"],
) -> Iterable[tuple[ArtifactKind, str]]:
"""Yield manifest-declared and convention-based candidate names."""
if manifest is not None:
if layer == "preset":
declarations = (
(entry.get("type"), entry)
for entry in manifest.templates
if isinstance(entry, dict)
)
else:
declarations = (
(kind, entry)
for kind, entries in (
("command", manifest.commands),
("template", manifest.templates),
("script", manifest.scripts),
)
for entry in entries
if isinstance(entry, dict)
)
for kind, contribution in declarations:
name = contribution.get("name")
if (
kind in ("command", "template", "script")
and isinstance(name, str)
and name
and ":" not in name
):
yield kind, name
yield from ((kind, name) for kind, name, _path in _iter_convention_contributions(pack_dir))
def _iter_project_override_candidates(
self,
resolver: Any,
) -> Iterable[tuple[ArtifactKind, str]]:
"""Yield candidate ``(kind, name)`` pairs for project overrides.
A root ``overrides/<name>.md`` file is the override for both the
``template`` and the ``command`` lookup of ``<name>``. Both candidates
are emitted and the normal inventory resolution path decides whether
each is present.
"""
overrides_dir = resolver.overrides_dir
if not overrides_dir.is_dir():
return
for entry in sorted(overrides_dir.iterdir(), key=lambda p: p.name):
if not entry.is_file() or entry.suffix != _TEMPLATE_SUFFIX:
continue
name = entry.stem
if not _is_valid_artifact_name_component(name, "command"):
continue
for kind in ("command", "template"):
yield kind, name
scripts_dir = overrides_dir / "scripts"
if not scripts_dir.is_dir():
return
for entry in sorted(scripts_dir.iterdir(), key=lambda p: p.name):
if entry.is_file() and entry.suffix == _SCRIPT_SUFFIX:
if not _is_valid_artifact_name_component(entry.stem, "script"):
continue
yield "script", entry.stem
def _iter_core_candidates(
self, core_script_paths: dict[str, Path]
) -> Iterable[tuple[ArtifactKind, str]]:
"""Yield candidate names from resolver-compatible core asset paths."""
from ..extensions import CORE_COMMAND_NAMES # lazy: avoids circular import
from ..presets import PresetResolver
project_commands_dir = _project_core_asset_root(self.project_root, "commands")
bundled_commands_dir = _locate_shared_asset_dir("commands")
command_dirs = tuple(
directory
for directory in (project_commands_dir, bundled_commands_dir)
if directory is not None
)
command_names = {_core_command_logical_name(name) for name in CORE_COMMAND_NAMES}
for directory in command_dirs:
for entry in sorted(directory.iterdir(), key=lambda p: p.name):
if entry.is_file() and entry.suffix == _TEMPLATE_SUFFIX:
command_names.add(_core_command_logical_name(entry.stem))
for name in sorted(command_names):
if any(
(directory / f"{candidate}.md").is_file()
for directory in command_dirs
for candidate in (
name,
*(
(PresetResolver._core_stem(name),)
if PresetResolver._core_stem(name)
else ()
),
)
if candidate is not None
):
yield "command", name
seen_templates: set[str] = set()
for directory in (
_project_core_asset_root(self.project_root, "templates"),
_locate_shared_asset_dir("templates"),
):
if directory is None:
continue
for entry in sorted(directory.iterdir(), key=lambda p: p.name):
if (
entry.is_file()
and entry.suffix == _TEMPLATE_SUFFIX
and entry.stem not in seen_templates
):
seen_templates.add(entry.stem)
yield "template", entry.stem
for directory in (
_project_core_asset_root(self.project_root, "scripts"),
_locate_shared_asset_dir("scripts"),
):
if directory is None:
continue
for entry in sorted(directory.glob(f"*{_SCRIPT_SUFFIX}"), key=lambda p: p.name):
yield "script", entry.stem
yield from (("script", name) for name in sorted(core_script_paths))
def _selected_core_script_paths(self) -> dict[str, Path]:
"""Return built-in scripts selected by the project's existing runtime policy."""
from .._init_options import load_init_options
from ..agents import CommandRegistrar
from ..integrations.base import IntegrationBase
command_dirs = tuple(
directory
for directory in (
_project_core_asset_root(self.project_root, "commands"),
_locate_shared_asset_dir("commands"),
)
if directory is not None
)
script_dirs = tuple(
directory
for directory in (
_project_core_asset_root(self.project_root, "scripts"),
_locate_shared_asset_dir("scripts"),
)
if directory is not None
)
requested = load_init_options(self.project_root).get("script")
selected: dict[str, Path] = {}
for command_dir in command_dirs:
for template_path in sorted(command_dir.glob("*.md"), key=lambda p: p.name):
try:
content = template_path.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
frontmatter, _body = CommandRegistrar.parse_frontmatter(content)
scripts = frontmatter.get("scripts", {})
if not isinstance(scripts, dict):
continue
script_commands = {
key: value
for key, value in scripts.items()
if isinstance(key, str) and isinstance(value, str) and value.strip()
}
if not script_commands:
continue
try:
variant = IntegrationBase.select_script_variant(
requested, script_commands
)
tokens = shlex.split(script_commands[variant], posix=True)
except (KeyError, ValueError):
continue
if not tokens:
continue
path = None
for script_dir in script_dirs:
path = _resolve_script_reference(script_dir, tokens[0])
if path is not None:
break
if path is None:
continue
name = path.stem.replace("_", "-") if variant == "py" else path.stem
selected.setdefault(name, path)
return selected
def _describe_layer(
self,
resolver: Any,
layer: dict[str, Any],
kind: ArtifactKind,
name: str,
manifest_cache: dict[Path, Any | None],
) -> str:
"""Return manifest metadata or on-disk metadata for one resolver layer."""
manifest_description = self._manifest_description_for_layer(
resolver, layer, kind, name, manifest_cache
)
if manifest_description:
return manifest_description
path = layer.get("path")
if isinstance(path, Path):
return _describe_artifact_file(path, kind)
return ""
def _manifest_description_for_layer(
self,
resolver: Any,
layer: dict[str, Any],
kind: ArtifactKind,
name: str,
manifest_cache: dict[Path, Any | None],
) -> str:
provenance = _layer_provenance(
resolver, layer, kind, name, manifest_cache
)
entry = provenance.manifest_entry
if entry is None:
return ""
description = entry.get("description", "")
return description if isinstance(description, str) else ""
_CONVENTION_SUBDIRS: tuple[tuple[str, ArtifactKind, str], ...] = (
("commands", "command", _TEMPLATE_SUFFIX),
("templates", "template", _TEMPLATE_SUFFIX),
("scripts", "script", _SCRIPT_SUFFIX),
)
def _iter_convention_contributions(
pack_dir: Path,
) -> Iterable[tuple[ArtifactKind, str, Path]]:
"""Yield ``(kind, name, path)`` for files exposed by convention.
Templates are also accepted at the pack root for legacy compatibility,
matching the resolver's ``templates/``-then-root lookup order.
"""
for subdir, kind, suffix in _CONVENTION_SUBDIRS:
candidate_dir = pack_dir / subdir
if not candidate_dir.is_dir():
continue
for entry in sorted(candidate_dir.iterdir(), key=lambda p: p.name):
if entry.is_file() and entry.suffix == suffix and ":" not in entry.stem:
yield kind, entry.stem, entry
if not pack_dir.is_dir():
return
for entry in sorted(pack_dir.iterdir(), key=lambda p: p.name):
if (
entry.is_file()
and entry.suffix == _TEMPLATE_SUFFIX
and ":" not in entry.stem
):
yield "template", entry.stem, entry