Skip to content

💫 Toolkit to help you get started with SDD or any other process!

19.7 KB
Raw Blame
"""Domain operations used by workflow overlay and resolve commands."""

from __future__ import annotations

import os
from pathlib import Path
from typing import Any

import typer
import yaml
from rich.markup import escape as _escape_markup

from ..._console import console, err_console
from ...extensions import normalize_priority
from .. import _commands as cli
from . import WorkflowResolver
from .schema import _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN, validate_overlay_yaml


def _validate_overlay_id_or_exit(id_value: str, label: str) -> None:
    """Validate a single-segment overlay/workflow id from CLI arguments."""
    if not isinstance(id_value, str) or not id_value:
        err_console.print(f"[red]Error:[/red] {label} is required and must be a non-empty string.")
        raise typer.Exit(1)
    if not _SAFE_ID_PATTERN.fullmatch(id_value):
        err_console.print(
            f"[red]Error:[/red] Invalid {label} {id_value!r}: "
            "only lowercase letters, digits, and hyphens are allowed."
        )
        raise typer.Exit(1)


def _validate_workflow_id_or_exit(workflow_id: str) -> None:
    """Validate a workflow id, treating the overlay root as reserved."""
    _validate_overlay_id_or_exit(workflow_id, "workflow ID")
    if workflow_id in _RESERVED_WORKFLOW_IDS:
        err_console.print(
            f"[red]Error:[/red] Invalid workflow ID {workflow_id!r}: "
            "reserved name."
        )
        raise typer.Exit(1)


def _overlay_root(project_root: Path) -> Path:
    """Return the project-local overlay root after rejecting unsafe ancestors."""
    cli._reject_unsafe_workflow_storage(project_root)
    root = project_root / ".specify" / "workflows" / "overlays"
    cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
    return root


def _project_overlay_dir(project_root: Path, workflow_id: str) -> Path:
    """Return the project-local overlay directory for a workflow id.

    Raises typer.Exit if the resolved path escapes the overlay root.
    """
    _validate_workflow_id_or_exit(workflow_id)
    root = _overlay_root(project_root)
    target = root / workflow_id
    return _ensure_contained_dir(target, root)


def _ensure_contained_dir(path: Path, root: Path) -> Path:
    """Ensure *path* resolves inside *root* and is not a symlink.

    Returns *path* if safe. Raises typer.Exit on traversal or symlink.
    """
    cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
    if path.is_symlink():
        err_console.print(
            f"[red]Error:[/red] Refusing to use symlinked path {path}."
        )
        raise typer.Exit(1)
    if path.exists() and not path.is_dir():
        err_console.print(
            f"[red]Error:[/red] Overlay directory path is not a directory: {path}."
        )
        raise typer.Exit(1)
    try:
        resolved = path.resolve()
        root_resolved = root.resolve()
        resolved.relative_to(root_resolved)
    except ValueError:
        err_console.print(
            f"[red]Error:[/red] Path traversal detected: {path} is outside the allowed directory."
        )
        raise typer.Exit(1)
    return path


def _find_overlay_file(project_root: Path, workflow_id: str, overlay_id: str) -> Path | None:
    """Locate a project-local overlay file by its manifest ID, not filename.

    Scans all YAML files in the overlay directory and matches on the ``id``
    field inside each manifest. This aligns with ``ProjectOverlaySource.collect()``
    which also derives identity from the manifest, not the filename.
    """
    _validate_workflow_id_or_exit(workflow_id)
    _validate_overlay_id_or_exit(overlay_id, "overlay ID")
    overlay_dir = _project_overlay_dir(project_root, workflow_id)
    if not overlay_dir.is_dir():
        return None
    try:
        entries = sorted(overlay_dir.iterdir())
    except OSError:
        return None
    matches: list[Path] = []
    for path in entries:
        if not path.is_file() or path.suffix not in (".yml", ".yaml"):
            continue
        if path.is_symlink():
            continue
        data, _ = _read_overlay(path)
        if data is None:
            continue
        if data.get("id") == overlay_id:
            matches.append(path)
    if len(matches) > 1:
        paths = ", ".join(str(path) for path in matches)
        err_console.print(
            f"[red]Error:[/red] Duplicate overlay ID '{overlay_id}' in {paths}. "
            "Resolve the duplicate manifest IDs before continuing."
        )
        raise typer.Exit(1)
    return matches[0] if matches else None


def _ensure_contained_path(path: Path, root: Path) -> Path:
    """Return *path* only if it resolves inside *root*; otherwise raise typer.Exit."""
    cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
    if path.is_symlink():
        err_console.print(
            f"[red]Error:[/red] Refusing to use symlinked path {path}."
        )
        raise typer.Exit(1)
    try:
        resolved = path.resolve()
        root_resolved = root.resolve()
        resolved.relative_to(root_resolved)
    except ValueError:
        err_console.print(
            f"[red]Error:[/red] Path traversal detected: {path} is outside the allowed directory."
        )
        raise typer.Exit(1)
    return path


def _read_overlay(path: Path) -> tuple[dict[str, Any] | None, list[str]]:
    """Read and parse an overlay YAML file, returning (data, errors)."""
    try:
        content = path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        return None, [f"Failed to read {path}: {exc}"]
    try:
        data = yaml.safe_load(content)
    except yaml.YAMLError as exc:
        return None, [f"Invalid YAML in {path}: {exc}"]
    if not isinstance(data, dict):
        return None, [f"Overlay {path} must be a YAML mapping."]
    return data, []


def workflow_overlay_add(
    project_root: Path,
    source: Path,
    priority: int | None = None,
) -> Path | None:
    """Add a project-local overlay from a YAML file.

    Returns the path of the installed overlay file, or None on failure.
    """
    cli._reject_unsafe_workflow_storage(project_root)
    data, errors = _read_overlay(source)
    if data is None:
        for err in errors:
            err_console.print(f"[red]Error:[/red] {err}")
        return None

    # Apply --priority override before validation so a valid CLI priority
    # can fix a missing or invalid priority in the file.
    if priority is not None:
        if isinstance(priority, bool) or not isinstance(priority, int) or priority < 1:
            err_console.print("[red]Error:[/red] Priority must be >= 1.")
            return None
        data["priority"] = normalize_priority(priority)

    overlay, validation_errors = validate_overlay_yaml(data)
    if overlay is None:
        err_console.print("[red]Error:[/red] Overlay validation failed:")
        for err in validation_errors:
            err_console.print(f"  \u2022 {err}")
        return None
    data["priority"] = overlay.priority

    target_dir = _project_overlay_dir(project_root, overlay.extends)
    # Reuse an existing .yaml file so we don't create a duplicate .yml layer.
    existing = _find_overlay_file(project_root, overlay.extends, overlay.id)
    if existing is not None:
        target_path = existing
    else:
        target_path = _ensure_contained_path(
            target_dir / f"{overlay.id}.yml", _overlay_root(project_root)
        )
        # Overlay identity is the manifest ``id``, not the filename (see
        # ``_find_overlay_file``), so ``<id>.yml`` can legitimately already hold
        # a DIFFERENT overlay. Committing onto it would destroy that overlay
        # permanently -- the commit renames the victim to a ``.bak`` and the
        # success path then discards that backup -- while reporting success.
        # ``lexists`` rather than ``is_file``: the latter is False for a
        # directory, FIFO or socket, so those bypassed this guard entirely and
        # reached ``_commit_workflow_file``, which renames whatever is there to
        # a ``.bak`` sibling and then discards it on the success path. A
        # directory occupant was moved aside and the command still reported
        # success -- it survived only because unlinking a directory happens to
        # fail. A FIFO or socket has no such accident and is simply gone.
        if os.path.lexists(target_path):
            if target_path.is_symlink() or not target_path.is_file():
                err_console.print(
                    f"[red]Error:[/red] {_escape_markup(str(target_path))} exists "
                    f"and is not a regular file. Rename or remove it before "
                    f"adding overlay {_escape_markup(repr(overlay.id))}."
                )
                return None
            # Fail closed: refuse unless the occupant is provably this same
            # overlay. Reaching here means ``_find_overlay_file`` did not match
            # this path, and it skips exactly the files whose identity cannot be
            # established -- unreadable, malformed, non-mapping, or missing a
            # usable ``id``. Letting those through would destroy the user's file
            # just as permanently as overwriting a valid one, only without even
            # being able to name what was lost.
            occupant, read_errors = _read_overlay(target_path)
            occupant_id = occupant.get("id") if isinstance(occupant, dict) else None
            if not (isinstance(occupant_id, str) and occupant_id == overlay.id):
                if isinstance(occupant_id, str) and occupant_id:
                    detail = f"already holds overlay {_escape_markup(repr(occupant_id))}"
                elif read_errors:
                    detail = (
                        "could not be parsed as an overlay "
                        f"({_escape_markup('; '.join(read_errors))})"
                    )
                else:
                    detail = "is not a readable overlay manifest (no usable 'id')"
                err_console.print(
                    f"[red]Error:[/red] {_escape_markup(str(target_path))} {detail}. "
                    f"Rename or remove it before adding overlay "
                    f"{_escape_markup(repr(overlay.id))}."
                )
                return None

    backup: Path | None = None
    try:
        target_dir.mkdir(parents=True, exist_ok=True)
        existed_before = target_path.exists()
        staged = cli._stage_workflow_file(target_path.parent)
        try:
            # ``allow_unicode=True`` matches every other YAML writer in the
            # repo. Without it every non-ASCII character in a hand-authored
            # overlay is rewritten as a ``\uXXXX`` escape, so merely toggling
            # an overlay makes the user's own file unreadable.
            staged.write_bytes(
                yaml.safe_dump(data, sort_keys=False, allow_unicode=True).encode(
                    "utf-8"
                )
            )
            backup = cli._commit_workflow_file(staged, target_path, existed_before)
        except BaseException:
            cli._safe_discard_staged_workflow_file(
                staged, target_path.parent, existed_before
            )
            raise
    except OSError as exc:
        err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")
        return None
    cli._discard_committed_backup_file(backup)

    console.print(
        f"[green]\u2713[/green] Overlay '{overlay.id}' added for workflow '{overlay.extends}'"
    )
    return target_path


def _update_overlay_field(
    project_root: Path,
    workflow_id: str,
    overlay_id: str,
    field: str,
    value: Any,
) -> bool:
    """Update a single field in a project-local overlay file."""
    cli._reject_unsafe_workflow_storage(project_root)
    path = _find_overlay_file(project_root, workflow_id, overlay_id)
    if path is None:
        err_console.print(
            f"[red]Error:[/red] Overlay '{overlay_id}' not found for workflow '{workflow_id}'"
        )
        return False

    data, errors = _read_overlay(path)
    if data is None:
        for err in errors:
            err_console.print(f"[red]Error:[/red] {err}")
        return False

    data[field] = value
    overlay, validation_errors = validate_overlay_yaml(data)
    if overlay is None:
        err_console.print("[red]Error:[/red] Overlay validation failed:")
        for err in validation_errors:
            err_console.print(f"  \u2022 {err}")
        return False

    backup: Path | None = None
    try:
        existed_before = path.exists()
        staged = cli._stage_workflow_file(path.parent)
        try:
            # ``allow_unicode=True`` matches every other YAML writer in the
            # repo. Without it every non-ASCII character in a hand-authored
            # overlay is rewritten as a ``\uXXXX`` escape, so merely toggling
            # an overlay makes the user's own file unreadable.
            staged.write_bytes(
                yaml.safe_dump(data, sort_keys=False, allow_unicode=True).encode(
                    "utf-8"
                )
            )
            backup = cli._commit_workflow_file(staged, path, existed_before)
        except BaseException:
            cli._safe_discard_staged_workflow_file(
                staged, path.parent, existed_before
            )
            raise
    except OSError as exc:
        err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")
        return False
    cli._discard_committed_backup_file(backup)

    return True


def workflow_overlay_set_priority(
    project_root: Path,
    workflow_id: str,
    overlay_id: str,
    priority: int,
) -> bool:
    """Set the priority of a project-local overlay."""
    if isinstance(priority, bool) or not isinstance(priority, int) or priority < 1:
        err_console.print("[red]Error:[/red] Priority must be >= 1.")
        raise typer.Exit(1)
    normalized_priority = normalize_priority(priority)
    if _update_overlay_field(
        project_root, workflow_id, overlay_id, "priority", normalized_priority
    ):
        console.print(
            f"[green]\u2713[/green] Priority of overlay '{overlay_id}' set to {normalized_priority}"
        )
        return True
    return False


def workflow_overlay_enable(
    project_root: Path,
    workflow_id: str,
    overlay_id: str,
) -> bool:
    """Enable a project-local overlay."""
    if _update_overlay_field(project_root, workflow_id, overlay_id, "enabled", True):
        console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' enabled")
        return True
    return False


def workflow_overlay_disable(
    project_root: Path,
    workflow_id: str,
    overlay_id: str,
) -> bool:
    """Disable a project-local overlay."""
    if _update_overlay_field(project_root, workflow_id, overlay_id, "enabled", False):
        console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' disabled")
        return True
    return False


def workflow_overlay_remove(
    project_root: Path,
    workflow_id: str,
    overlay_id: str,
) -> bool:
    """Remove a project-local overlay file."""
    cli._reject_unsafe_workflow_storage(project_root)
    path = _find_overlay_file(project_root, workflow_id, overlay_id)
    if path is None:
        err_console.print(
            f"[red]Error:[/red] Overlay '{overlay_id}' not found for workflow '{workflow_id}'"
        )
        return False

    try:
        path.unlink()
    except OSError as exc:
        err_console.print(f"[red]Error:[/red] Failed to remove overlay: {exc}")
        return False

    console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' removed")
    return True


def workflow_overlay_list(project_root: Path, workflow_id: str) -> list[dict[str, Any]] | None:
    """List all overlays for a workflow and print a summary table.

    Returns the raw list data for machine-readable callers, or None on error.
    """
    cli._reject_unsafe_workflow_storage(project_root)
    _validate_workflow_id_or_exit(workflow_id)
    resolver = WorkflowResolver(project_root)
    try:
        layers = resolver.collect_all_layers(workflow_id, include_disabled=True)
    except ValueError as exc:
        err_console.print(f"[red]Error:[/red] {exc}")
        return None
    overlays = [layer for layer in layers if layer.tier != "base"]

    if not overlays:
        console.print(f"[yellow]No overlays found for workflow '{workflow_id}'.[/yellow]")
        return []

    console.print(f"Overlays for workflow '{workflow_id}':")
    rows: list[dict[str, Any]] = []
    for layer in overlays:
        overlay = layer.content
        rows.append({
            "id": overlay.id,
            "source": layer.source,
            "tier": layer.tier,
            "priority": normalize_priority(overlay.priority),
            "enabled": overlay.enabled,
            "path": str(layer.path) if layer.path else None,
        })
        enabled_marker = "enabled" if overlay.enabled else "disabled"
        console.print(
            f"  \u2022 {overlay.id} (priority={normalize_priority(overlay.priority)}, "
            f"source={layer.source}, {enabled_marker})"
        )
    return rows


def workflow_resolve(project_root: Path, workflow_id: str) -> dict[str, Any] | None:
    """Print layer attribution for a resolved workflow.

    Returns a serializable attribution payload.
    """
    cli._reject_unsafe_workflow_storage(project_root)
    _validate_workflow_id_or_exit(workflow_id)
    resolver = WorkflowResolver(project_root)
    try:
        definition, layers, attribution = resolver.resolve_with_layers(workflow_id)
    except FileNotFoundError:
        err_console.print(
            f"[red]Error:[/red] Workflow '{workflow_id}' not found"
        )
        return None
    except ValueError as exc:
        err_console.print(f"[red]Error:[/red] {exc}")
        return None

    console.print(f"Resolved workflow '{workflow_id}':")
    # The list is sorted by (priority, source) ascending, which puts the
    # winning layer first only while priorities DIFFER. On a tie the sort is
    # alphabetical by source while the merge gives the conflict to the LAST id
    # (docs/reference/workflows.md, overlays section), so the plain "highest
    # precedence first" label stated the opposite of the outcome printed
    # directly beneath it in the same output -- in the one command whose job
    # is explaining which overlay won. Spell the tie-break out rather than
    # reorder the list, which
    # `test_workflow_resolve_equal_priority_layers_sort_by_source` pins.
    console.print(
        "Layers (highest precedence first; on equal priority the last ID wins):"
    )
    for layer in layers:
        priority = (
            "n/a" if layer.tier == "base" else str(normalize_priority(layer.priority))
        )
        # ``\[`` keeps the literal bracket: unescaped, Rich parses ``[base]`` /
        # ``[project-overlay]`` as a style tag and swallows the tier label whole.
        console.print(
            f"  \u2022 \\[{_escape_markup(layer.tier)}] "
            f"{_escape_markup(layer.source)} "
            f"(priority={priority})"
        )

    console.print("Step attribution:")
    for composed in attribution:
        # Step IDs come from base-workflow / overlay YAML, which only bans ``:``
        # \u2014 brackets pass validation, so they reach Rich as markup. A balanced
        # ``[stuff]`` is swallowed; an unbalanced ``[/red]`` raises MarkupError.
        console.print(
            f"  \u2022 {_escape_markup(composed.step_id)}: "
            f"{_escape_markup(composed.source)}"
        )

    return {
        "workflow_id": workflow_id,
        "layers": [
            {
                "source": layer.source,
                "tier": layer.tier,
                "priority": (
                    None
                    if layer.tier == "base"
                    else normalize_priority(layer.priority)
                ),
            }
            for layer in layers
        ],
        "attribution": [
            {"step_id": composed.step_id, "source": composed.source}
            for composed in attribution
        ],
    }