π« Toolkit to help you get started with SDD or any other process!
"""Implementation of ``specify bundle info``."""
from __future__ import annotations
import json as _json
from pathlib import Path
import typer
from rich.markup import escape as _escape_markup
from .._console import console
from .._file_policy import ProjectPolicyError
from . import BundlerError
from ._commands import (
_build_stack,
_bundle_overlaps,
_expand_manifest,
_fail,
_trust_badge,
_trust_level,
bundle_app,
)
from .conflict import effective_setting
from .project import find_project_root
from .sources import _download_manifest
from .versioning import same_version, strip_version_prefix
@bundle_app.command("info")
def bundle_info(
bundle_id: str = typer.Argument(..., help="Bundle id to inspect"),
offline: bool = typer.Option(False, "--offline", help="Do not access the network"),
as_json: bool = typer.Option(False, "--json", help="Emit JSON to stdout"),
versions: bool = typer.Option(False, "--versions", help="List catalog versions"),
) -> None:
"""Show full metadata and the fully expanded component set (== what install adds)."""
try:
project_root = find_project_root() or Path.cwd()
stack = _build_stack(project_root, offline=offline)
resolved = stack.resolve(bundle_id)
if versions is True:
from .catalog_versions import available_versions
available = available_versions(resolved.entry)
if as_json:
print(
_json.dumps(
{
"id": resolved.entry.id,
"versions": available,
"current": resolved.entry.version,
"source": resolved.source.id,
"install_policy": resolved.source.install_policy.value,
},
indent=2,
)
)
return
console.print(
f"Catalog versions for {_escape_markup(str(resolved.entry.id))}:"
)
for index, available_version in enumerate(available):
current = " (current)" if index == 0 else ""
console.print(f" {_escape_markup(available_version)}{current}")
console.print(
f" Source: {_escape_markup(str(resolved.source.id))} "
f"({resolved.source.install_policy.value})"
)
if not resolved.install_allowed:
console.print(
"[yellow]Discovery only; catalog installation is disabled.[/yellow]"
)
return
# `info` must show the fully expanded component set that `install` would
# apply (contracts/cli-commands.md). Expansion happens regardless of
# install policy β discovery-only bundles stay inspectable; only
# `install` is refused. But if the manifest itself can't be resolved
# (e.g. --offline against an https:// download_url, or a download
# failure), fail loudly and exit non-zero rather than silently
# degrading to catalog `provides` counts, so users never mistake an
# unverifiable bundle for a known/installable one.
manifest = _download_manifest(resolved, offline=offline)
expanded = _expand_manifest(
project_root,
manifest,
offline=offline,
stack=stack,
download=_download_manifest,
)
except BundlerError as exc:
_fail(str(exc), as_json=as_json and isinstance(exc.__cause__, ProjectPolicyError))
return
if expanded.has_references:
overlaps = _bundle_overlaps(
project_root,
manifest,
offline=offline,
components=expanded.components,
)
else:
# Preserve the flat command's established call shape and rendering.
overlaps = _bundle_overlaps(project_root, manifest, offline=offline)
components = _manifest_component_view(expanded)
entry = resolved.entry
if as_json:
payload = {
"id": entry.id,
"name": entry.name,
"version": entry.version,
"role": entry.role,
"description": entry.description,
"author": entry.author,
"license": entry.license,
"source": resolved.source.id,
"install_policy": resolved.source.install_policy.value,
"provides": entry.provides,
"requires": {"speckit_version": entry.requires_speckit_version},
"verified": entry.verified,
"trust": _trust_level(entry.verified),
"integration": (
manifest.integration.id if manifest and manifest.integration else None
),
"components": components,
"overlaps": overlaps,
}
if expanded.has_references:
payload["references"] = _reference_view(expanded)
print(_json.dumps(payload, indent=2))
return
console.print(
f"\n[bold cyan]{_escape_markup(str(entry.id))}[/bold cyan] "
f"v{_escape_markup(str(entry.version))} β "
f"{_escape_markup(str(entry.name))}"
)
console.print(f" Role: {_escape_markup(str(entry.role))}")
console.print(f" {_escape_markup(str(entry.description))}")
console.print(
f" Author: {_escape_markup(str(entry.author))} "
f"License: {_escape_markup(str(entry.license))}"
)
console.print(
f" Source: {_escape_markup(str(resolved.source.id))} "
f"({resolved.source.install_policy.value})"
)
console.print(f" Trust: {_trust_badge(entry.verified)}")
if entry.requires_speckit_version:
console.print(
f" Requires Spec Kit: "
f"{_escape_markup(str(entry.requires_speckit_version))}"
)
if manifest and manifest.integration:
console.print(f" Integration: {_escape_markup(str(manifest.integration.id))}")
if expanded.has_references:
console.print("\n [bold]References:[/bold]")
for reference in expanded.references:
console.print(f" - {_escape_markup(_format_reference(reference))}")
if components:
console.print("\n [bold]Components[/bold] (added on install):")
for kind in ("extensions", "presets", "steps", "workflows"):
items = [c for c in components if c["kind"] == kind]
if not items:
continue
console.print(f" [bold]{kind}:[/bold]")
for item in items:
console.print(f" - {_escape_markup(_format_component(item))}")
else:
console.print("\n [bold]Provides:[/bold]")
for kind in ("extensions", "presets", "steps", "workflows"):
count = entry.provides.get(kind, 0)
if count:
console.print(f" {kind}: {_escape_markup(str(count))}")
if overlaps:
console.print("\n [yellow]Overlaps with already-installed bundles:[/yellow]")
for overlap in overlaps:
console.print(f" [yellow]-[/yellow] {_escape_markup(str(overlap))}")
if not resolved.install_allowed:
console.print(
"\n [yellow]This source is discovery-only; the bundle cannot be "
"installed from here.[/yellow]"
)
def _manifest_component_view(expanded) -> list[dict]:
"""Flatten an expanded manifest to JSON-friendly component dictionaries."""
if expanded is None:
return []
view: list[dict] = []
for component in expanded.components:
item = {
"kind": component.kind,
"id": component.id,
"version": component.version,
}
if expanded.has_references and component.source is not None:
item["source"] = component.source
if component.priority is not None:
item["priority"] = component.priority
if component.strategy is not None:
item["strategy"] = component.strategy
if expanded.has_references:
origin = expanded.origins.get((component.kind, component.id))
if origin is not None and origin.origin:
item["origin"] = list(origin.origin)
if origin is not None and origin.overrides:
item["overrides"] = [
_component_provenance(override.component, override.origin)
for override in origin.overrides
]
view.append(item)
return view
def _component_provenance(component, origin: tuple[str, ...]) -> dict:
item = {
"version": component.version,
"origin": list(origin),
}
if component.source is not None:
item["source"] = component.source
if component.priority is not None:
item["priority"] = component.priority
if component.strategy is not None:
item["strategy"] = component.strategy
return item
def _reference_view(expanded) -> list[dict]:
return [
{
"id": reference.id,
"version": reference.version,
"source": reference.source_id,
"install_policy": (
"install-allowed" if reference.install_allowed else "discovery-only"
),
"via": list(reference.via),
"verified": reference.verified,
"trust": _trust_level(reference.verified),
}
for reference in expanded.references
]
def _format_reference(reference) -> str:
# The label supplies its own "v", and an accepted pin may already carry one
# (``v1.0.1``); strip it here so the text shows one prefix. The JSON view
# keeps the recorded spelling.
label = f"{reference.id} v{strip_version_prefix(reference.version)}"
label += f" ({reference.source_id}"
label += f"; {_trust_level(reference.verified)}"
if reference.via:
label += f"; via {' β '.join(reference.via)}"
if not reference.install_allowed:
label += "; discovery-only, not installable"
label += ")"
return label
def _format_component(item: dict) -> str:
label = f"{item['id']} v{item['version']}" if item.get("version") else item["id"]
extras = []
if item.get("priority") is not None:
extras.append(f"priority={item['priority']}")
if item.get("strategy") is not None:
extras.append(f"strategy={item['strategy']}")
origin = item.get("origin")
if origin:
extras.append(f"from {' β '.join(origin)}")
for override in item.get("overrides", []):
extras.append(_format_override(item, override))
if extras:
label += f" ({', '.join(extras)})"
return label
def _format_override(item: dict, override: dict) -> str:
"""Describe the settings replaced by an overriding component."""
changed: list[str] = []
old_version = override.get("version")
current_version = item.get("version")
versions_differ = (old_version is None) != (current_version is None)
if (
versions_differ
or (
old_version is not None
and current_version is not None
and not same_version(current_version, old_version)
)
):
changed.append(str(old_version) if old_version else "unpinned")
kind = item.get("kind")
for field in ("source", "priority", "strategy"):
if kind is None:
# Provenance without a kind compares raw values.
differs = override.get(field) != item.get(field)
else:
differs = effective_setting(
kind, field, override.get(field)
) != effective_setting(kind, field, item.get(field))
if differs:
value = override.get(field)
changed.append(f"{field}={value if value is not None else '<unset>'}")
origin = " β ".join(override.get("origin", []))
if not changed:
# Equivalent copies stay in the history; don't invent a difference.
return f"also declared by {origin} (same as final)"
return f"overrides {', '.join(changed)} from {origin}"