π« Toolkit to help you get started with SDD or any other process!
"""Implementation of ``specify bundle install``."""
from __future__ import annotations
from pathlib import Path
import typer
from rich.markup import escape as _escape_markup
from .._console import console
from . import BundlerError
from .expansion import require_installable
from ._commands import (
_build_stack,
_bundle_overlaps,
_expand_manifest,
_default_script_type,
_fail_with_notes,
_render_install_warnings,
_resolve_init_integration,
_run_init,
_speckit_version,
bundle_app,
)
from .project import active_integration, require_project_root
from .sources import (
_download_manifest,
_local_manifest_source,
_validate_manifest_structure,
)
@bundle_app.command("install")
def bundle_install(
bundle_id: str = typer.Argument(
...,
help="Bundle id (from the catalog stack) or a local path to a .zip "
"artifact, bundle directory, or bundle.yml",
),
integration: str = typer.Option(None, "--integration", help="Override integration"),
offline: bool = typer.Option(False, "--offline", help="Do not access the network"),
refresh: bool = typer.Option(
False,
"--refresh",
help="Refresh owned components from this bundle source",
),
version: str | None = typer.Option(
None,
"--version",
help="Install an exact bundle release from the catalog",
),
) -> None:
"""Install a bundle's full component set through each primitive's machinery.
``bundle_id`` may be a catalog bundle id, or a local path to a built
artifact (``.zip``), a bundle directory, or a ``bundle.yml`` file. Local
sources install directly without consulting the catalog stack, unless
the manifest declares ``provides.bundles``: a local parent's references
resolve through the catalog stack and need network access. Use
``--refresh`` to update owned components from a newer local source.
"""
try:
# Direct callers such as ``bundle init`` receive Typer's OptionInfo
# default rather than a parsed option.
if not isinstance(version, str):
version = None
if version is not None:
if not version.strip():
raise BundlerError("--version must not be blank.")
if Path(bundle_id).expanduser().exists():
raise BundlerError(
"--version requires a catalog bundle ID, not a local path."
)
if refresh:
raise BundlerError("--version cannot be used with --refresh.")
from .project import find_project_root
from .adapters import DefaultPrimitiveInstaller
from .installer import install_bundle
from .resolver import resolve_install_plan
project_root = find_project_root()
stack = None
local_manifest = _local_manifest_source(bundle_id)
if local_manifest is not None:
manifest = local_manifest
_validate_manifest_structure(
manifest,
source=f"Local bundle source {bundle_id!r}",
)
else:
stack = _build_stack(project_root or Path.cwd(), offline=offline)
resolved = stack.resolve(bundle_id, version)
if not resolved.install_allowed:
raise BundlerError(
f"Bundle '{bundle_id}' resolves only from a discovery-only source "
f"('{resolved.source.id}'); it cannot be installed from there."
)
manifest = _download_manifest(resolved, offline=offline)
expanded = _expand_manifest(
project_root or Path.cwd(),
manifest,
offline=offline,
stack=stack,
download=_download_manifest,
)
require_installable(expanded)
if project_root is None:
init_integration = _resolve_init_integration(integration, manifest)
# Resolve all hard compatibility gates before ``specify init``.
# Otherwise an incompatible but structurally valid bundle would
# initialize a project and only then fail its version/integration
# checks, leaving state behind after a failed install.
resolve_install_plan(
expanded,
speckit_version=_speckit_version(),
active_integration=init_integration,
integration_explicit=True,
)
console.print(
f"[cyan]No Spec Kit project here; initializing with integration "
f"'{_escape_markup(str(init_integration))}'β¦[/cyan]"
)
_run_init(
init_integration, script_type=_default_script_type(), offline=offline
)
project_root = require_project_root()
for overlap in _bundle_overlaps(
project_root,
manifest,
offline=offline,
components=expanded.components,
):
console.print(f"[yellow]![/yellow] {_escape_markup(str(overlap))}")
# For an already-initialized project, the project's recorded active
# integration is authoritative β an explicit --integration must not be
# able to bypass the FR-019 integration-clash guard. The override only
# selects the integration at init time (handled above) or confirms the
# target when the active integration cannot be determined.
detected = active_integration(project_root)
plan = resolve_install_plan(
expanded,
speckit_version=_speckit_version(),
active_integration=detected if detected is not None else integration,
integration_explicit=bool(integration) and detected is None,
)
for warning in plan.warnings:
console.print(f"[yellow]![/yellow] {_escape_markup(str(warning))}")
result = install_bundle(
project_root,
plan,
DefaultPrimitiveInstaller(allow_network=not offline),
manifest=manifest,
refresh=refresh,
)
except BundlerError as exc:
_fail_with_notes(exc)
return
_render_install_warnings(result)
refresh_summary = (
f", {len(result.refreshed)} refreshed, {len(result.uninstalled)} removed"
if refresh
else ""
)
console.print(
f"[green]β[/green] Installed '{_escape_markup(str(result.bundle_id))}' "
f"({len(result.installed)} added, {len(result.skipped)} already present"
f"{refresh_summary})."
)