Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

19.1 KB
Raw Blame
"""Implementation of the ``specify preset add`` command."""

from __future__ import annotations

import os
from pathlib import Path

import typer
from packaging.version import InvalidVersion, Version
from rich.markup import escape as _escape_markup

from .._console import console
from .._download_security import (
    archive_format_from_name,
    archive_suffix,
    detect_archive_format,
    is_https_or_localhost_http,
    is_safe_download_redirect,
)
from . import _commands
from ._catalog_versions import select_release
from ._commands import preset_app


def _warn_unmet_extension_dependencies(manager, manifest) -> None:
    """Warn when a preset's declared extension dependencies are unsatisfied.

    A preset whose command overrides call into an extension is inert without
    it, but the overrides still fall through to the core workflow, so nothing
    breaks -- it just silently does less than the user expects. Naming the
    missing extension and the command that installs it turns that silence into
    something actionable. See issue #4231.
    """
    from ..extensions._commands import _command_safe_id

    unmet = manager.find_unmet_extension_dependencies(manifest)
    if not unmet:
        return

    console.print()
    console.print(
        "[yellow]![/yellow]  This preset depends on extensions that are not satisfied:"
    )
    needs_catalog = False
    for dep in unmet:
        uses_catalog = False
        extension_id = _escape_markup(dep["id"])
        # The displayed id only needs Rich escaping, but a suggested command
        # has to survive Typer's parser: `^[a-z0-9-]+$` admits a leading
        # hyphen, so an id like `--force` would render as an option rather
        # than the positional argument. _command_safe_id substitutes a
        # placeholder in that case, the same way extension commands do.
        command_id = _command_safe_id(dep["id"])
        reason = dep["reason"]
        # The remediation has to match the reason. `extension add` refuses an
        # already-installed extension without --force, and `extension update`
        # only moves forward to the catalog release. A general PEP 440
        # constraint may require an exact version, an upper bound, or a
        # downgrade, so do not promise that update will satisfy it.
        if reason == "missing":
            console.print(f"    [yellow]{extension_id}[/yellow] is not installed")
            label, remedy = "Install with", f"specify extension add {command_id}"
            uses_catalog = True
        elif reason == "corrupt":
            console.print(
                f"    [yellow]{extension_id}[/yellow] has an unreadable registry entry"
            )
            # is_installed() still counts the key, so a plain add is refused.
            label = "Reinstall with"
            remedy = f"specify extension add {command_id} --force"
            uses_catalog = True
        elif reason == "stale":
            console.print(
                f"    [yellow]{extension_id}[/yellow] is registered but its "
                "files are missing"
            )
            label = "Reinstall with"
            remedy = f"specify extension add {command_id} --force"
            uses_catalog = True
        elif reason == "disabled":
            console.print(
                f"    [yellow]{extension_id}[/yellow] is installed but disabled"
            )
            label, remedy = "Enable with", f"specify extension enable {command_id}"
        else:
            console.print(
                f"    [yellow]{extension_id}[/yellow] "
                f"{_escape_markup(dep['installed'])} does not satisfy "
                f"{_escape_markup(dep['version'])}"
            )
            label = "Needs"
            remedy = (
                f"a release of {command_id} satisfying {_escape_markup(dep['version'])}"
            )
        console.print(f"      {label}: {remedy}")
        needs_catalog = needs_catalog or uses_catalog
    console.print()
    # The consequence differs by reason and must not be overstated. An
    # unavailable extension contributes nothing, so those features are simply
    # inert. A version mismatch is the opposite: the extension is installed and
    # enabled, so the preset does invoke it -- the combination is just untested
    # against the declared constraint, which is not the same as "safe".
    console.print("[dim]The preset is installed.[/dim]")
    if any(
        dep["reason"] in ("missing", "corrupt", "stale", "disabled") for dep in unmet
    ):
        console.print(
            "[dim]Anything relying on an unavailable extension does nothing "
            "until that is resolved.[/dim]"
        )
    if any(dep["reason"] == "version" for dep in unmet):
        console.print(
            "[dim]Where only a version constraint is unmet the extension is "
            "still used, so it may not behave as the preset expects.[/dim]"
        )
    if needs_catalog:
        # `extension add <id>` resolves through the catalogs, and the default
        # community catalog is discovery-only, so installing by id is refused
        # for anything listed only there -- true of every extension motivating
        # this feature. Knowing which applies would mean a catalog fetch, and
        # this runs on an install path that touches no network, so describe
        # the outcome instead of asserting the command succeeds. The rejection
        # itself prints the exact --from form, so this is a signpost rather
        # than a dead end.
        console.print(
            "[dim]If an extension is listed only in a discovery-only catalog, "
            "that command is refused and prints the "
            "--from <archive-url> form to use instead.[/dim]"
        )


# ===== Preset Commands =====


@preset_app.command("add")
def preset_add(
    preset_id: str = typer.Argument(None, help="Preset ID to install from catalog"),
    from_url: str = typer.Option(
        None,
        "--from",
        help="Install from a .zip, .tar.gz, or .tgz URL",
    ),
    dev: str = typer.Option(
        None, "--dev", help="Install from local directory (development mode)"
    ),
    priority: int = typer.Option(
        10,
        "--priority",
        help="Resolution priority (lower = higher precedence, default 10)",
    ),
    version: str | None = typer.Option(
        None, "--version", help="Install an exact version from a catalog"
    ),
):
    """Install a preset."""
    from .. import _locate_bundled_preset, _require_specify_project, get_speckit_version
    from . import (
        PresetCatalog,
        PresetCompatibilityError,
        PresetError,
        PresetManager,
        PresetValidationError,
    )

    project_root = _require_specify_project()
    _commands._validate_priority(priority)
    # Direct callers of the command function receive Typer's OptionInfo default.
    if not isinstance(version, str):
        version = None
    if version is not None and (
        not version.strip()
        or dev is not None
        or from_url is not None
        or not preset_id
    ):
        console.print(
            "[red]Error:[/red] --version requires a catalog preset ID "
            "(without --dev or --from)."
        )
        raise typer.Exit(1)

    manager = PresetManager(project_root)
    speckit_version = get_speckit_version()

    try:
        if dev:
            dev_path = Path(dev).resolve()
            if not dev_path.exists():
                console.print(f"[red]Error:[/red] Directory not found: {dev}")
                raise typer.Exit(1)

            console.print(f"Installing preset from [cyan]{dev_path}[/cyan]...")
            manifest = manager.install_from_directory(
                dev_path, speckit_version, priority
            )
            console.print(
                f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})"
            )

        elif from_url:
            # Validate URL scheme before downloading
            from urllib.parse import urlparse as _urlparse

            try:
                _parsed = _urlparse(from_url)
                _ = _parsed.port
            except ValueError:
                console.print(
                    f"[red]Error:[/red] Invalid URL: {_escape_markup(from_url)}"
                )
                raise typer.Exit(1)

            def _validate_download_redirect(old_url, new_url):
                if not is_safe_download_redirect(old_url, new_url):
                    import urllib.error

                    raise urllib.error.URLError(
                        "redirect target must use HTTPS without entering a local "
                        "target, or stay within loopback over HTTP"
                    )

            if not is_https_or_localhost_http(from_url):
                console.print(
                    "[red]Error:[/red] URL must use HTTPS with a hostname and be "
                    "a valid URL with a host. HTTP is only allowed for localhost, "
                    "127.0.0.1, and ::1."
                )
                raise typer.Exit(1)

            console.print(
                f"Installing preset from [cyan]{_escape_markup(from_url)}[/cyan]..."
            )
            import tempfile
            import urllib.error

            with tempfile.TemporaryDirectory() as tmpdir:
                archive_path = Path(tmpdir) / "preset.archive"
                try:
                    from specify_cli.authentication.github_http import (
                        resolve_github_release_asset_api_url,
                    )
                    from specify_cli.authentication.http import github_provider_hosts
                    from specify_cli.authentication.http import open_url as _open_url

                    _preset_extra_headers = None
                    _resolved_from_url = resolve_github_release_asset_api_url(
                        from_url, _open_url, github_hosts=github_provider_hosts()
                    )
                    if _resolved_from_url:
                        from_url = _resolved_from_url
                        _preset_extra_headers = {"Accept": "application/octet-stream"}

                    with _open_url(
                        from_url,
                        timeout=60,
                        extra_headers=_preset_extra_headers,
                        redirect_validator=_validate_download_redirect,
                    ) as response:
                        final_url = (
                            response.geturl()
                            if hasattr(response, "geturl")
                            else from_url
                        )
                        if not is_https_or_localhost_http(final_url):
                            console.print(
                                "[red]Error:[/red] Preset URL redirected to a disallowed URL: "
                                f"{final_url}. Redirect targets must use HTTPS with a hostname, "
                                "or HTTP for localhost (127.0.0.1, ::1)."
                            )
                            raise typer.Exit(1)
                        archive_data = _commands.read_response_limited(
                            response,
                            error_type=PresetError,
                            label=f"preset {from_url}",
                        )
                        content_type = (
                            response.getheader("Content-Type")
                            if hasattr(response, "getheader")
                            else None
                        )
                    archive_path.write_bytes(archive_data)
                    format_source = (
                        final_url
                        if archive_format_from_name(final_url) is not None
                        else from_url
                    )
                    archive_format = detect_archive_format(
                        archive_path,
                        source_name=format_source,
                        content_type=content_type,
                        error_type=PresetError,
                    )
                    detected_path = archive_path.with_suffix(
                        archive_suffix(archive_format)
                    )
                    os.replace(archive_path, detected_path)
                    archive_path = detected_path
                except (urllib.error.URLError, PresetError) as e:
                    console.print(
                        f"[red]Error:[/red] Failed to download: "
                        f"{_escape_markup(str(e))}"
                    )
                    raise typer.Exit(1)

                manifest = manager.install_from_zip(
                    archive_path,
                    speckit_version,
                    priority,
                )

            console.print(
                f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})"
            )

        elif preset_id:
            # Try bundled preset first, then catalog
            bundled_path = _locate_bundled_preset(preset_id) if version is None else None
            if bundled_path:
                console.print(f"Installing bundled preset [cyan]{preset_id}[/cyan]...")
                manifest = manager.install_from_directory(
                    bundled_path, speckit_version, priority
                )
                console.print(
                    f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})"
                )
            else:
                catalog = PresetCatalog(project_root)
                pack_info = catalog.get_pack_info(preset_id)

                if not pack_info:
                    console.print(
                        f"[red]Error:[/red] Preset '{preset_id}' not found in catalog"
                    )
                    raise typer.Exit(1)

                if version is not None:
                    if not pack_info.get("_install_allowed", True):
                        console.print(
                            f"[red]Error:[/red] Preset '{_escape_markup(preset_id)}' "
                            "is from a discovery-only catalog (install not allowed)."
                        )
                        raise typer.Exit(1)
                    selected = select_release(pack_info, version)
                    if selected is None:
                        console.print(
                            f"[red]Error:[/red] Preset '{_escape_markup(preset_id)}' "
                            f"has no catalog release for version {_escape_markup(version)}."
                        )
                        raise typer.Exit(1)
                    pack_info = selected

                # Bundled presets should have been caught above; if we reach
                # here the bundled files are missing from the installation.
                if pack_info.get("bundled") and not pack_info.get("download_url"):
                    packaged = _locate_bundled_preset(preset_id)
                    if version is not None and packaged is not None:
                        from . import PresetManifest

                        packaged_manifest = PresetManifest(packaged / "preset.yml")
                        try:
                            matches = Version(packaged_manifest.version) == Version(
                                pack_info["version"]
                            )
                        except InvalidVersion:
                            matches = False
                        if packaged_manifest.id == preset_id and matches:
                            manifest = manager.install_from_directory(
                                packaged, speckit_version, priority
                            )
                            console.print(
                                f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})"
                            )
                            _commands._warn_unmet_extension_dependencies(manager, manifest)
                            return
                    from ..extensions import REINSTALL_COMMAND

                    console.print(
                        f"[red]Error:[/red] Preset '{_escape_markup(preset_id)}' is bundled with spec-kit "
                        "but the requested version could not be found in the installed package."
                    )
                    console.print(
                        "\nThis usually means the spec-kit installation is incomplete or corrupted."
                    )
                    console.print("Try reinstalling spec-kit:")
                    console.print(f"  {REINSTALL_COMMAND}")
                    raise typer.Exit(1)

                if not pack_info.get("_install_allowed", True):
                    catalog_name = pack_info.get("_catalog_name", "unknown")
                    console.print(
                        f"[red]Error:[/red] Preset '{preset_id}' is from the '{catalog_name}' catalog which is discovery-only (install not allowed)."
                    )
                    console.print(
                        "Add the catalog with --install-allowed or install from the preset's repository directly with --from."
                    )
                    raise typer.Exit(1)

                console.print(
                    f"Installing preset [cyan]{pack_info.get('name', preset_id)}[/cyan]..."
                )

                try:
                    archive_path = (
                        catalog.download_pack_info(pack_info)
                        if version is not None
                        else catalog.download_pack(preset_id)
                    )
                    manifest = manager.install_from_zip(
                        archive_path,
                        speckit_version,
                        priority,
                        catalog_name=pack_info.get("_catalog_name"),
                        **(
                            {"expected_id": preset_id, "expected_version": pack_info["version"]}
                            if version is not None
                            else {}
                        ),
                    )
                    console.print(
                        f"[green]βœ“[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})"
                    )
                finally:
                    if "archive_path" in locals() and archive_path.exists():
                        archive_path.unlink(missing_ok=True)
        else:
            console.print(
                "[red]Error:[/red] Specify a preset ID, --from URL, or --dev path"
            )
            raise typer.Exit(1)

        # Every install path above binds `manifest` and the no-source branch
        # exits, so one call here covers --dev, --from, and catalog installs
        # alike. Warns rather than fails: the preset is installed and its
        # overrides fall through to the core workflow without the extension.
        _commands._warn_unmet_extension_dependencies(manager, manifest)

    except PresetCompatibilityError as e:
        console.print(f"[red]Compatibility Error:[/red] {_escape_markup(str(e))}")
        raise typer.Exit(1)
    except PresetValidationError as e:
        console.print(f"[red]Validation Error:[/red] {_escape_markup(str(e))}")
        raise typer.Exit(1)
    except PresetError as e:
        console.print(f"[red]Error:[/red] {_escape_markup(str(e))}")
        raise typer.Exit(1)