💫 Toolkit to help you get started with SDD or any other process!
"""Shared application operation for ``artifact.info``."""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal
from .._file_policy import ProjectPolicyError, project_files
from ..presets import PresetError
from . import (
AmbiguousArtifactError,
ArtifactCatalog,
ArtifactError,
ArtifactKind,
ArtifactNotFoundError,
ArtifactResolutionError,
NotASpecKitProjectError,
)
from ._identifiers import (
IdentifierComponentError,
derive_hook_public_id,
derive_public_id,
parse_hook_artifact_name,
validate_component,
)
from .models import HookStackEntry, StackLayer
NamedArtifactKind = Literal["command", "template", "script"]
@dataclass(frozen=True)
class ArtifactInfoRequest:
"""Explicit project context and artifact selection for ``artifact.info``."""
project_directory: Path
identifier: str
kind: ArtifactKind | None = None
@dataclass(frozen=True)
class ArtifactInfoNamedArtifact:
"""One named artifact and its complete ordered composition stack."""
id: str
name: str
kind: NamedArtifactKind
description: str
stack: tuple[StackLayer, ...]
def to_json_dict(self) -> dict[str, Any]:
return {
"id": self.id,
"name": self.name,
"kind": self.kind,
"description": self.description,
"stack": [entry.to_json_dict() for entry in self.stack],
}
@dataclass(frozen=True)
class ArtifactInfoHookArtifact:
"""One hook artifact and its additive declaration stack."""
id: str
name: str
kind: Literal["hook"]
description: str
eventName: str
targetCommand: str
registered: bool
stack: tuple[HookStackEntry, ...]
def to_json_dict(self) -> dict[str, Any]:
return {
"id": self.id,
"name": self.name,
"kind": self.kind,
"description": self.description,
"eventName": self.eventName,
"targetCommand": self.targetCommand,
"registered": self.registered,
"stack": [entry.to_json_dict() for entry in self.stack],
}
ArtifactInfoArtifact = ArtifactInfoNamedArtifact | ArtifactInfoHookArtifact
@dataclass(frozen=True)
class ArtifactInfoResult:
"""Transport-neutral typed artifact information."""
artifact: ArtifactInfoArtifact
def to_json_dict(self) -> dict[str, Any]:
return self.artifact.to_json_dict()
class ArtifactInfoError(ArtifactError):
"""Expected transport-neutral failure from ``artifact.info``."""
code: str
details: dict[str, Any]
retryable: bool
def __init__(
self,
*,
code: str,
message: str,
details: dict[str, Any],
retryable: bool = False,
) -> None:
self.code = code
self.message = message
self.details = details
self.retryable = retryable
super().__init__(message)
class ArtifactInfoProjectDirectoryError(ArtifactInfoError):
"""The supplied project directory is not an absolute path."""
def __init__(self, project_directory: Path) -> None:
super().__init__(
code="invalid_project_directory",
message="project_directory must be an absolute path",
details={"project_directory": str(project_directory)},
)
class ArtifactInfoProjectError(ArtifactInfoError):
"""The supplied directory is not a Spec Kit project root."""
def __init__(self, project_directory: Path) -> None:
super().__init__(
code="not_a_spec_kit_project",
message="not a Spec Kit project: no .specify/ directory found",
details={"project_directory": str(project_directory)},
)
class ArtifactInfoKindError(ArtifactInfoError):
"""The requested artifact family is not supported."""
def __init__(self, kind: object) -> None:
super().__init__(
code="invalid_artifact_kind",
message=(
f"invalid artifact kind {kind!r}: expected one of "
"command, template, script, hook"
),
details={"kind": kind},
)
class ArtifactInfoIdentifierError(ArtifactInfoError):
"""The artifact identifier is structurally invalid."""
def __init__(self, identifier: object) -> None:
super().__init__(
code="invalid_artifact_identifier",
message=f"unknown artifact {identifier}",
details={"identifier": identifier},
)
class ArtifactInfoNotFoundError(ArtifactInfoError):
"""No named artifact matched the request."""
def __init__(self, identifier: str) -> None:
super().__init__(
code="unknown_artifact",
message=f"unknown artifact {identifier}",
details={"identifier": identifier},
)
class ArtifactInfoHookNotFoundError(ArtifactInfoError):
"""No hook artifact matched the request."""
def __init__(self, identifier: str) -> None:
super().__init__(
code="unknown_hook",
message=f"unknown artifact {identifier}",
details={"identifier": identifier},
)
class ArtifactInfoAmbiguousError(ArtifactInfoError):
"""A bare artifact name matched more than one artifact family."""
def __init__(self, identifier: str, message: str) -> None:
super().__init__(
code="ambiguous_artifact",
message=message,
details={"identifier": identifier},
)
class ArtifactInfoResolutionError(ArtifactInfoError):
"""Artifact composition could not be resolved."""
def __init__(
self, project_directory: Path, identifier: str, *,
message: str = "artifact resolution failed",
) -> None:
super().__init__(
code="artifact_resolution_failed",
message=message,
details={
"project_directory": str(project_directory),
"identifier": identifier,
},
)
class ArtifactInfoInvalidResultError(ArtifactInfoError):
"""The catalog returned an incomplete or inconsistent result."""
def __init__(self, project_directory: Path, identifier: str) -> None:
super().__init__(
code="invalid_operation_result",
message="artifact resolution failed",
details={
"project_directory": str(project_directory),
"identifier": identifier,
},
)
@dataclass(frozen=True)
class ArtifactInfoOperationDescriptor:
"""Stable metadata shared by delivery adapters for ``artifact.info``."""
operation_id: Literal["artifact.info"]
contract_version: Literal["1"]
request_type: type[ArtifactInfoRequest]
result_type: type[ArtifactInfoResult]
warning_types: tuple[type[object], ...]
error_types: tuple[type[ArtifactInfoError], ...]
capabilities: frozenset[Literal["local-read"]]
network_access: Literal["none"]
ARTIFACT_INFO_OPERATION = ArtifactInfoOperationDescriptor(
operation_id="artifact.info",
contract_version="1",
request_type=ArtifactInfoRequest,
result_type=ArtifactInfoResult,
warning_types=(),
error_types=(
ArtifactInfoProjectDirectoryError,
ArtifactInfoProjectError,
ArtifactInfoKindError,
ArtifactInfoIdentifierError,
ArtifactInfoNotFoundError,
ArtifactInfoHookNotFoundError,
ArtifactInfoAmbiguousError,
ArtifactInfoResolutionError,
ArtifactInfoInvalidResultError,
),
capabilities=frozenset({"local-read"}),
network_access="none",
)
_NAMED_RESULT_KEYS = {"id", "name", "kind", "description", "stack"}
_HOOK_RESULT_KEYS = {
"id",
"name",
"kind",
"description",
"eventName",
"targetCommand",
"registered",
"stack",
}
_STACK_KEYS = {
"id",
"layer",
"sourceId",
"presetId",
"presetName",
"strategy",
"active",
"hidden",
"manifestPath",
"lookupId",
"sourcePath",
}
_HOOK_STACK_KEYS = {
*_STACK_KEYS,
"priority",
"optional",
}
def _is_optional_string(value: object) -> bool:
return value is None or isinstance(value, str)
def _invalid_result(request: ArtifactInfoRequest) -> ArtifactInfoInvalidResultError:
return ArtifactInfoInvalidResultError(
Path(request.project_directory),
request.identifier,
)
def _convert_named_stack(
value: object,
*,
artifact_id: str,
request: ArtifactInfoRequest,
) -> tuple[StackLayer, ...]:
if not isinstance(value, list) or not value:
raise _invalid_result(request)
entries: list[StackLayer] = []
for item in value:
if not isinstance(item, dict) or set(item) != _STACK_KEYS:
raise _invalid_result(request)
if (
item["id"] != artifact_id
or item["layer"] not in (None, "project", "preset", "extension")
or not _is_optional_string(item["sourceId"])
or not _is_optional_string(item["presetId"])
or not _is_optional_string(item["presetName"])
or item["strategy"] not in ("replace", "wrap", "prepend", "append")
or not isinstance(item["active"], bool)
or not isinstance(item["hidden"], bool)
or not _is_optional_string(item["manifestPath"])
or not _is_optional_string(item["lookupId"])
or not _is_optional_string(item["sourcePath"])
):
raise _invalid_result(request)
entries.append(StackLayer(**item))
return tuple(entries)
def _convert_hook_stack(
value: object,
*,
artifact_id: str,
request: ArtifactInfoRequest,
) -> tuple[HookStackEntry, ...]:
if not isinstance(value, list) or not value:
raise _invalid_result(request)
entries: list[HookStackEntry] = []
for item in value:
if not isinstance(item, dict) or set(item) != _HOOK_STACK_KEYS:
raise _invalid_result(request)
priority = item["priority"]
if (
item["id"] != artifact_id
or item["layer"] not in ("preset", "extension")
or not isinstance(item["sourceId"], str)
or not _is_optional_string(item["presetId"])
or not _is_optional_string(item["presetName"])
or item["strategy"] != "additive"
or not isinstance(item["active"], bool)
or not isinstance(item["hidden"], bool)
or not isinstance(item["manifestPath"], str)
or not isinstance(item["lookupId"], str)
or item["sourcePath"] is not None
or isinstance(priority, bool)
or not isinstance(priority, int)
or not isinstance(item["optional"], bool)
):
raise _invalid_result(request)
entries.append(HookStackEntry(**item))
return tuple(entries)
def _convert_catalog_result(
payload: object,
request: ArtifactInfoRequest,
) -> ArtifactInfoResult:
if not isinstance(payload, dict):
raise _invalid_result(request)
kind = payload.get("kind")
if kind == "hook":
if set(payload) != _HOOK_RESULT_KEYS:
raise _invalid_result(request)
artifact_id = payload["id"]
name = payload["name"]
description = payload["description"]
event_name = payload["eventName"]
target_command = payload["targetCommand"]
if (
not isinstance(artifact_id, str)
or not isinstance(name, str)
or not isinstance(description, str)
or not isinstance(event_name, str)
or not isinstance(target_command, str)
or not isinstance(payload["registered"], bool)
):
raise _invalid_result(request)
try:
expected_id = derive_hook_public_id(event_name, target_command)
except IdentifierComponentError as exc:
raise _invalid_result(request) from exc
if artifact_id != expected_id or name != artifact_id.removeprefix("hook:"):
raise _invalid_result(request)
return ArtifactInfoResult(
artifact=ArtifactInfoHookArtifact(
id=artifact_id,
name=name,
kind="hook",
description=description,
eventName=event_name,
targetCommand=target_command,
registered=payload["registered"],
stack=_convert_hook_stack(
payload["stack"],
artifact_id=artifact_id,
request=request,
),
)
)
if kind not in ("command", "template", "script"):
raise _invalid_result(request)
if set(payload) != _NAMED_RESULT_KEYS:
raise _invalid_result(request)
artifact_id = payload["id"]
name = payload["name"]
description = payload["description"]
if (
not isinstance(artifact_id, str)
or not isinstance(name, str)
or not isinstance(description, str)
):
raise _invalid_result(request)
try:
expected_id = derive_public_id(kind, name)
except IdentifierComponentError as exc:
raise _invalid_result(request) from exc
if artifact_id != expected_id:
raise _invalid_result(request)
return ArtifactInfoResult(
artifact=ArtifactInfoNamedArtifact(
id=artifact_id,
name=name,
kind=kind,
description=description,
stack=_convert_named_stack(
payload["stack"],
artifact_id=artifact_id,
request=request,
),
)
)
def _validate_identifier(identifier: str, kind: ArtifactKind | None) -> None:
if kind == "hook":
if identifier.startswith("hook:"):
try:
parse_hook_artifact_name(identifier.removeprefix("hook:"))
except IdentifierComponentError:
pass
else:
return
try:
parse_hook_artifact_name(identifier)
except IdentifierComponentError as exc:
raise ArtifactInfoIdentifierError(identifier) from exc
return
if ":" not in identifier:
return
prefix, _, bare = identifier.partition(":")
if prefix in ("command", "template", "script"):
try:
validate_component(bare, f"{prefix} name")
except IdentifierComponentError as exc:
raise ArtifactInfoIdentifierError(identifier) from exc
return
if prefix == "hook":
try:
parse_hook_artifact_name(bare)
except IdentifierComponentError as exc:
raise ArtifactInfoIdentifierError(identifier) from exc
return
raise ArtifactInfoIdentifierError(identifier)
def _requests_hook(identifier: str, kind: ArtifactKind | None) -> bool:
return kind == "hook" or (kind is None and identifier.startswith("hook:"))
def get_artifact_info(request: ArtifactInfoRequest) -> ArtifactInfoResult:
"""Return typed artifact information for an explicit Spec Kit project."""
project_directory = Path(request.project_directory)
if not project_directory.is_absolute():
raise ArtifactInfoProjectDirectoryError(project_directory)
if request.kind is not None and request.kind not in (
"command",
"template",
"script",
"hook",
):
raise ArtifactInfoKindError(request.kind)
if not isinstance(request.identifier, str) or not request.identifier:
raise ArtifactInfoIdentifierError(request.identifier)
_validate_identifier(request.identifier, request.kind)
try:
if project_directory.is_dir():
project_files(project_directory)
except ProjectPolicyError as exc:
raise ArtifactInfoResolutionError(
project_directory, request.identifier, message=str(exc),
) from exc
if not (project_directory / ".specify").is_dir():
raise ArtifactInfoProjectError(project_directory)
try:
payload = ArtifactCatalog(project_directory).get_artifact_info(
request.identifier,
kind=request.kind,
)
except NotASpecKitProjectError as exc:
raise ArtifactInfoProjectError(project_directory) from exc
except AmbiguousArtifactError as exc:
raise ArtifactInfoAmbiguousError(request.identifier, exc.message) from exc
except ArtifactNotFoundError as exc:
if _requests_hook(request.identifier, request.kind):
raise ArtifactInfoHookNotFoundError(request.identifier) from exc
raise ArtifactInfoNotFoundError(request.identifier) from exc
except ArtifactResolutionError as exc:
raise ArtifactInfoResolutionError(
project_directory, request.identifier, message=exc.message,
) from exc
except (OSError, PresetError) as exc:
raise ArtifactInfoResolutionError(
project_directory,
request.identifier,
) from exc
return _convert_catalog_result(payload, request)