π« Toolkit to help you get started with SDD or any other process!
"""Shared infrastructure and registration for ``specify artifact`` commands.
Command handlers live in ``command_*.py`` modules. Domain behavior remains in
Typer-free modules in this package, following ``design/cli.md``.
"""
from __future__ import annotations
import contextlib
import io
import json
import sys
from pathlib import Path
import typer
from . import (
ArtifactError,
ArtifactResolutionError,
NotASpecKitProjectError,
)
artifact_app = typer.Typer(
name="artifact",
help="Introspect commands, templates, scripts, and hooks Spec Kit exposes.",
no_args_is_help=True,
)
def _resolve_project_root() -> Path:
"""Return the project root without emitting Rich output on failure.
Delegates to :func:`specify_cli._require_specify_project` β the same
resolution chokepoint every other project-scoped subcommand (``preset``,
``extension``, ``workflow``, ...) uses, including its ``SPECIFY_INIT_DIR``
override handling. That helper prints Rich error output and raises
``typer.Exit`` on failure, which would corrupt the strict JSON envelope
``specify artifact list --json`` and ``specify artifact info --json``
emit on stdout/stderr. The Rich output is suppressed here and the
Missing-project failures become :class:`NotASpecKitProjectError`; policy
failures retain their actionable message for the shared JSON error handler.
"""
from .. import _require_specify_project # lazy: avoids circular import
from .._file_policy import ProjectPolicyError
from .._project import ProjectResolutionError
with contextlib.redirect_stderr(io.StringIO()):
try:
root = _require_specify_project()
except typer.Exit as exc:
cause = exc.__cause__
if isinstance(cause, ProjectResolutionError) and isinstance(
cause.__cause__, ProjectPolicyError
):
error = ArtifactError(str(cause))
error.message = str(cause)
raise error from exc
raise NotASpecKitProjectError() from None
from ..integrations.installer import (
IntegrationInstallError,
load_installed_integrations,
)
try:
load_installed_integrations(root)
except (IntegrationInstallError, OSError) as exc:
raise ArtifactResolutionError(str(exc)) from exc
return root
def _emit_error_and_exit(exc: ArtifactError) -> None:
"""Write ``{"error": "..."}`` to stderr and exit with code 1.
The stdout stream is left completely untouched β the contract is that
machine consumers can rely on an empty stdout when the exit code is
non-zero, so no partial JSON payload leaks even on a late-stage failure.
"""
payload = json.dumps({"error": exc.message}, ensure_ascii=False)
print(payload, file=sys.stderr)
raise typer.Exit(code=1)
def _require_json_flag(json_flag: bool) -> None:
"""Enforce the opt-in ``--json`` contract shared by artifact commands.
A text-mode formatter is intentionally deferred so the initial release
can commit to exactly one output shape. Callers that omit ``--json``
get a usage error (exit 2) with no stdout output β this makes future
addition of a default text renderer a purely additive, non-breaking
change.
"""
if json_flag:
return
print(
"specify artifact requires --json for now; text output is not yet implemented.",
file=sys.stderr,
)
raise typer.Exit(code=2)
def register(app: typer.Typer) -> None:
"""Attach the artifact command group to the root Typer app."""
# isort: off
from . import command_list # noqa: F401 β registers handler via decorator
from . import command_info # noqa: F401 β registers handler via decorator
from . import command_lookup # noqa: F401 β registers handler via decorator
# isort: on
app.add_typer(artifact_app, name="artifact")