Skip to content

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

5.1 KB
Raw Blame
"""Shared project-resolution helpers for the Specify CLI."""

from __future__ import annotations

import json
import os
from pathlib import Path
from typing import NoReturn

import typer
from rich.markup import escape

from ._console import err_console
from ._file_policy import ProjectPolicyError, project_files
from .file_helper import FileHelper

try:
    from typer._click.globals import get_current_context
except ModuleNotFoundError as error:
    if error.name != "typer._click":
        raise
    from click import get_current_context


class ProjectResolutionError(RuntimeError):
    """A project-root error that callers can render for their own surface."""


def _resolve_init_dir_override_unrendered() -> Path | None:
    """Resolve ``SPECIFY_INIT_DIR`` without emitting user-facing output."""
    raw = os.environ.get("SPECIFY_INIT_DIR", "")
    if not raw:
        return None
    try:
        init_root = (Path.cwd() / raw).resolve()
    except (OSError, RuntimeError) as exc:
        raise ProjectResolutionError(
            f"Cannot resolve SPECIFY_INIT_DIR '{raw}': {exc}"
        ) from exc
    if not init_root.is_dir():
        raise ProjectResolutionError(
            f"SPECIFY_INIT_DIR does not point to an existing directory: {raw}"
        )
    preflight_project_policy(init_root)
    if not (init_root / ".specify").is_dir():
        raise ProjectResolutionError(
            "SPECIFY_INIT_DIR is not a Spec Kit project "
            f"(no .specify/ directory): {init_root}"
        )
    return init_root


def preflight_project_policy(project_root: Path) -> None:
    """Validate at the resolved project boundary without printing or caching."""
    try:
        project_files(project_root)
    except ProjectPolicyError as exc:
        marker = project_root / ".specify"
        if marker.is_symlink():
            raise ProjectResolutionError(
                f"Refusing to use symlinked .specify path: {marker}. {exc}"
            ) from exc
        if marker.exists() and not marker.is_dir():
            raise ProjectResolutionError(
                f"Not a Spec Kit project: .specify path exists but is not a directory: {marker}"
            ) from exc
        raise ProjectResolutionError(str(exc)) from exc


def _resolve_init_dir_override() -> Path | None:
    """Resolve the ``SPECIFY_INIT_DIR`` project override for the Python CLI.

    Applies the same validation rules as the shell resolver
    (``resolve_specify_init_dir`` in ``scripts/bash/common.sh``): the value names
    the project root β€” the directory *containing* ``.specify/`` β€” and is strict.
    Relative paths resolve against the current directory; the path must exist and
    contain ``.specify/``, otherwise this hard-errors with no fallback to cwd
    (which would silently operate on the wrong project's files). The error
    messages mirror the shell resolver's wording (rendered here as a Rich
    ``Error:`` line, plain ``ERROR:`` in the shell) so the two surfaces read
    consistently.

    Returns the validated absolute project root, or ``None`` when the variable is
    unset/empty, in which case callers keep their existing cwd-based behavior.

    Note: this canonicalizes symlinks via :meth:`Path.resolve` (physical path),
    whereas the shell ``cd -- "$X" && pwd`` keeps the logical path. The two agree
    for non-symlinked paths; a symlinked ``SPECIFY_INIT_DIR`` can resolve to
    different strings across the surfaces. The canonical form is the safer choice
    here (a stable project identity), so this is a deliberate, documented variance,
    not a parity guarantee on the resolved string.
    """
    try:
        return _resolve_init_dir_override_unrendered()
    except ProjectResolutionError as error:
        render_project_error(error)


def resolve_specify_project_root() -> Path:
    """Return the active project root without rendering errors.

    This is deliberately separate from ``_require_specify_project`` so the
    installed-list JSON contract can send structured failures to stderr without
    changing the Rich diagnostics used by every other project-scoped command.
    """
    override = _resolve_init_dir_override_unrendered()
    if override is not None:
        return override
    project_root = Path.cwd()
    preflight_project_policy(project_root)
    if not (project_root / ".specify").is_dir():
        raise ProjectResolutionError("Not a Spec Kit project (no .specify/ directory)")
    return project_root


def render_project_error(error: ProjectResolutionError) -> NoReturn:
    """Render a project failure on the current command's error surface."""
    context = get_current_context(silent=True)
    if context is not None and (
        context.params.get("json_output") is True or context.params.get("as_json") is True
    ):
        typer.echo(json.dumps({"error": str(error)}, ensure_ascii=False), err=True)
    else:
        err_console.print(f"[red]Error:[/red] {escape(str(error))}")
    raise typer.Exit(1) from error


def resolve_specify_project_files() -> FileHelper:
    """Resolve the active project and hand its current policy to domain consumers."""
    return project_files(resolve_specify_project_root())