π« Toolkit to help you get started with SDD or any other process!
"""Shared infrastructure and registration for ``specify bundle`` commands.
Command handlers live in ``command_*.py`` modules. The nested ``catalog``
namespace registers through ``bundles.catalog``; domain behavior remains in
Typer-free modules in this package.
"""
from __future__ import annotations
from pathlib import Path
from typing import TYPE_CHECKING
import typer
from rich.markup import escape as _escape_markup
from .._console import err_console
from . import BundlerError
from .project import active_integration
from .records import load_records
if TYPE_CHECKING:
from .installer import InstallResult
bundle_app = typer.Typer(
name="bundle",
help="Discover, install, and author Spec Kit bundles",
add_completion=False,
)
def _fail(message: str, *, as_json: bool = False) -> None:
"""Print an actionable error to stderr and exit non-zero."""
if as_json:
import json
typer.echo(json.dumps({"error": message}, ensure_ascii=False), err=True)
raise typer.Exit(code=1)
# Use the stderr console so the error never lands on stdout, which under
# ``--json`` carries the machine-readable payload and must stay parseable.
# Escape the message: every caller passes ``str(exc)`` from a BundlerError
# that interpolates untrusted data (a CLI argument, a catalog url, a
# bundle.yml field), so a '[...]' in it would be parsed as a Rich style tag
# -- silently swallowing the text, or raising MarkupError on an unbalanced
# closer and replacing the whole message with a traceback.
err_console.print(f"[red]Error:[/red] {_escape_markup(message)}", style=None)
raise typer.Exit(code=1)
def _fail_with_notes(exc: BaseException) -> None:
"""Exit with the original error first, then any recovery notes."""
notes = [str(note) for note in getattr(exc, "__notes__", ())]
message = str(exc) if not notes else f"{exc}\n" + "\n".join(notes)
_fail(message)
def _render_install_warnings(result: InstallResult) -> None:
for warning in result.warnings:
err_console.print(f"[yellow]Warning:[/yellow] {_escape_markup(warning.message)}")
def _user_config_dir() -> Path:
# User-scope Spec Kit config lives under ~/.specify (same convention as
# auth.json, extension/preset catalogs). Passing this through to the source
# stack is what makes the documented project > user > built-in precedence
# reachable from the CLI.
return Path.home() / ".specify"
def _build_stack(project_root: Path, *, offline: bool):
from .adapters import make_catalog_fetcher
from .catalog_stack import CatalogStack
fetcher = make_catalog_fetcher(allow_network=not offline)
return CatalogStack.load(project_root, fetcher, user_config_dir=_user_config_dir())
def _speckit_version() -> str:
from .._assets import get_speckit_version
return get_speckit_version()
def _trust_level(verified: bool) -> str:
"""Trust framing for a catalog entry (FR-010): org-curated vs community."""
return "verified" if verified else "community"
def _trust_badge(verified: bool) -> str:
return "[green]β verified[/green]" if verified else "[yellow]community[/yellow]"
def _default_script_type() -> str:
"""OS-appropriate default script flavor (FR-013)."""
import os
return "ps" if os.name == "nt" else "sh"
def _run_init(integration: str, *, script_type: str, offline: bool = False) -> None:
"""Idempotently scaffold a Spec Kit project here via the existing ``init`` machinery.
Reuses the real ``specify init`` command callback in-process (Principle I)
with ``--here --force`` so it is non-interactive and merges into the current
directory.
"""
from .. import app
init_cb = next(
c.callback
for c in app.registered_commands
if c.callback and c.callback.__name__ == "init"
)
try:
init_cb(
project_name=None,
script_type=script_type,
ignore_agent_tools=True,
here=True,
force=True,
allow_symlinks=False,
skip_tls=False,
debug=False,
github_token=None,
offline=offline,
preset=None,
integration=integration,
integration_options=None,
extensions=None,
trust_extension_urls=False,
)
except typer.Exit as exc:
if exc.exit_code:
raise BundlerError(
f"Failed to initialize a Spec Kit project (integration '{integration}')."
) from exc
def _resolve_init_integration(override: str | None, manifest) -> str:
"""Precedence (FR-013): explicit override β bundle-declared β default."""
from .._agent_config import resolve_default_init_integration
if override:
return override
if manifest is not None and manifest.integration is not None:
return manifest.integration.id
return resolve_default_init_integration()
def _expand_manifest(
project_root: Path,
manifest,
*,
offline: bool,
stack=None,
download,
):
"""Expand referenced bundles through the effective catalog stack.
Flat manifests deliberately bypass stack construction: local bundles with
no references must retain their existing offline, no-network behavior.
``download`` is supplied by the calling command so its established
monkeypatch point also controls referenced-manifest downloads.
"""
from .expansion import ExpandedManifest, expand_manifest
if not manifest.bundles:
return ExpandedManifest.flat(manifest)
from .sources import CatalogBundleLoader
if stack is None:
stack = _build_stack(project_root, offline=offline)
loader = CatalogBundleLoader(stack, offline=offline, download=download)
return expand_manifest(manifest, loader)
def _bundle_overlaps(
project_root: Path,
manifest,
*,
offline: bool,
components=None,
) -> list[str]:
"""Return informational overlaps between *manifest* and installed bundles."""
if manifest is None:
return []
try:
from .conflict import detect_conflicts
report = detect_conflicts(
manifest,
active_integration(project_root),
load_records(project_root),
components=components,
)
return [*report.overlaps, *report.version_clashes]
except BundlerError:
return []
def register(app: typer.Typer) -> None:
"""Attach the bundle command group to the root Typer app."""
from .catalog import register as register_catalog
register_catalog(bundle_app)
# isort: off
from . import command_search # noqa: F401 β registers handler via decorator
from . import command_info # noqa: F401 β registers handler via decorator
from . import command_list # noqa: F401 β registers handler via decorator
from . import command_install # noqa: F401 β registers handler via decorator
from . import command_add # noqa: F401 β registers handler via decorator
from . import command_update # noqa: F401 β registers handler via decorator
from . import command_remove # noqa: F401 β registers handler via decorator
from . import command_validate # noqa: F401 β registers handler via decorator
from . import command_build # noqa: F401 β registers handler via decorator
from . import command_init # noqa: F401 β registers handler via decorator
# isort: on
app.add_typer(bundle_app, name="bundle")