Skip to content

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

17.5 KB
Raw Blame
"""Gate step β€” human review gate."""

from __future__ import annotations

import json
import re
import sys
from pathlib import Path
from typing import Any

from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
from specify_cli.workflows.expressions import evaluate_expression

#: Control characters except tab: C0 (incl. LF, so an embedded newline cannot
#: break the boxed layout), DEL, and C1 (incl. ``\x9b`` CSI). Stripped from
#: anything derived from a ``show_file`` before it is printed β€” the file's
#: contents and the path itself β€” so neither can inject ANSI/terminal escapes.
_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0a-\x1f\x7f-\x9f]")


class GateStep(StepBase):
    """Interactive review gate.

    When running in an interactive terminal, prompts the user to choose
    an option (e.g. approve / reject).  Falls back to ``PAUSED`` when
    stdin is not a TTY (CI, piped input) so the run can be resumed
    later with ``specify workflow resume``.

    The user's choice is stored in ``output.choice``.  ``on_reject``
    controls abort / skip / retry behaviour.  ``verdict_input`` can name a
    workflow input to use as the choice when resuming non-interactively.
    """

    type_key = "gate"

    #: Maximum number of ``show_file`` lines rendered at the prompt, so a
    #: large file cannot flood the terminal before the choice.
    MAX_SHOW_FILE_LINES = 200

    def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
        message = config.get("message", "Review required.")
        if isinstance(message, str) and "{{" in message:
            message = evaluate_expression(message, context)
        # Keep JSON values typed; only values the JSON checkpoint cannot
        # persist (e.g. native YAML dates) are stored as text.
        try:
            json.dumps(message)
        except (TypeError, ValueError):
            message = str(message)

        options = config.get("options", ["approve", "reject"])
        on_reject = config.get("on_reject", "abort")
        has_verdict_input = "verdict_input" in config
        verdict_input = config.get("verdict_input")

        # ``validate`` rejects a non-list (or empty) ``options``, and requires
        # every option to be a string, but the engine does not auto-validate
        # before ``execute``. An unvalidated run with a scalar/dict/None
        # ``options`` would otherwise reach ``_prompt`` and crash the whole run
        # with a raw ``TypeError`` (``enumerate``/``len`` on a non-iterable) or
        # ``KeyError`` (indexing a dict); a non-string option would crash at the
        # ``choice.lower()`` reject check with ``AttributeError``. Fail this step
        # loudly instead β€” mirroring the switch 'cases' and command 'input'
        # guards. Checked before the non-TTY short-circuit so the error surfaces
        # in CI too, rather than PAUSING and crashing later on interactive resume.
        if (
            not isinstance(options, list)
            or not options
            or not all(isinstance(o, str) for o in options)
        ):
            return StepResult(
                status=StepStatus.FAILED,
                error=(
                    f"Gate step {config.get('id', '?')!r}: 'options' must be a "
                    f"non-empty list of strings, got {type(options).__name__}."
                ),
                output={
                    "message": message,
                    "options": options,
                    "on_reject": on_reject,
                    "choice": None,
                },
            )

        # ``validate`` rejects an ``on_reject`` outside abort/skip/retry, but the
        # engine does not auto-validate before ``execute``. The reject branch
        # below handles only "abort" and "retry" and then falls through to its
        # ``on_reject == "skip"`` case, so on an unvalidated run any other value
        # makes a REJECTED gate report COMPLETED and the run walks straight past
        # the review the gate exists to enforce. Reachable by a capitalisation
        # slip ("Abort"), a guessed verb ("fail", "stop"), a non-string, or the
        # ``None`` that a bare ``on_reject:`` yields -- note ``config.get(k,
        # default)`` does NOT substitute the default for an explicit null. Fail
        # loudly instead, mirroring the ``options``/``verdict_input`` guards here.
        if on_reject not in ("abort", "skip", "retry"):
            return StepResult(
                status=StepStatus.FAILED,
                error=(
                    f"Gate step {config.get('id', '?')!r}: 'on_reject' must be "
                    f"'abort', 'skip', or 'retry', got {on_reject!r}."
                ),
                output={
                    "message": message,
                    "options": options,
                    "on_reject": on_reject,
                    "choice": None,
                },
            )

        if has_verdict_input and (
            not isinstance(verdict_input, str) or not verdict_input
        ):
            return StepResult(
                status=StepStatus.FAILED,
                error=(
                    f"Gate step {config.get('id', '?')!r}: 'verdict_input' must be "
                    "a non-empty string."
                ),
            )

        if has_verdict_input and context.inside_fan_out:
            return StepResult(
                status=StepStatus.FAILED,
                error=(
                    f"Gate step {config.get('id', '?')!r}: 'verdict_input' is "
                    "not supported inside fan-out templates."
                ),
            )

        show_file = config.get("show_file")
        if isinstance(show_file, str) and "{{" in show_file:
            show_file = evaluate_expression(show_file, context)
        # ``evaluate_expression`` can return a non-string for a single
        # expression (e.g. a number from a prior step), and a literal
        # non-string is also possible; coerce so it is rendered rather
        # than silently skipped at the prompt.
        if show_file is not None:
            show_file = str(show_file)

        output = {
            "message": message,
            "options": options,
            "on_reject": on_reject,
            "show_file": show_file,
            "choice": None,
        }

        choice: str | None = None
        bound_verdict_input: str | None = None
        if verdict_input is not None:
            value = context.inputs.get(verdict_input)
            if value is not None and value != "":
                if not isinstance(value, str):
                    return StepResult(
                        status=StepStatus.FAILED,
                        output=output,
                        error=(
                            f"Gate step {config.get('id', '?')!r}: verdict input "
                            f"{verdict_input!r} must be a string, got "
                            f"{type(value).__name__}."
                        ),
                    )
                choice = next(
                    (option for option in options if option.lower() == value.lower()),
                    None,
                )
                if choice is None:
                    return StepResult(
                        status=StepStatus.FAILED,
                        output=output,
                        error=(
                            f"Gate step {config.get('id', '?')!r}: verdict input "
                            f"{verdict_input!r} value {value!r} does not match any "
                            "configured option."
                        ),
                    )
                bound_verdict_input = verdict_input

        if choice is None:
            # Non-interactive: pause for later resume (the file is not read here)
            if not sys.stdin.isatty():
                return StepResult(status=StepStatus.PAUSED, output=output)

            # Interactive: prompt the user. ``show_file`` contents are folded
            # into the displayed message so the operator can review the
            # referenced material before choosing. Composing the prompt text
            # here keeps ``_prompt`` to its ``(message, options)`` contract, so
            # adding review material never widens the interactive seam.
            choice = self._prompt(self._compose_prompt(message, show_file), options)
        output["choice"] = choice

        # Match rejection case-insensitively. ``_prompt`` echoes the option's
        # original casing, and ``validate`` accepts a reject option
        # case-insensitively (``o.lower() in {"reject", "abort"}``), so a gate
        # authored as ``options: [Approve, Reject]`` passes validation. Comparing
        # ``choice`` case-sensitively here would then treat a ``Reject`` pick as
        # approval and silently skip the abort β€” the reject path must agree with
        # the check that let the option through.
        if choice.lower() in ("reject", "abort"):
            if on_reject == "abort":
                output["aborted"] = True
                return StepResult(
                    status=StepStatus.FAILED,
                    output=output,
                    error=f"Gate rejected by user at step {config.get('id', '?')!r}",
                )
            if on_reject == "retry":
                # Pause so the next resume re-executes this gate
                if bound_verdict_input is not None:
                    context.inputs[bound_verdict_input] = ""
                return StepResult(status=StepStatus.PAUSED, output=output)
            # on_reject == "skip" β†’ completed, downstream steps decide
            return StepResult(status=StepStatus.COMPLETED, output=output)

        return StepResult(status=StepStatus.COMPLETED, output=output)

    @classmethod
    def _compose_prompt(cls, message: object, show_file: str | None) -> str:
        """Build the gate's display text.

        ``message`` may be a non-string (e.g. a YAML numeric literal that
        ``execute`` does not coerce), so it is rendered through ``str``.
        When ``show_file`` names a file, its contents (read safely, see
        ``_read_show_file``) are appended below the message so the operator
        can review the referenced material before choosing. Always returns a
        ``str`` β€” possibly multi-line β€” for ``_prompt`` to render in the box.
        """
        text = str(message)
        if not show_file:
            return text
        # The path is opened with the original value but displayed stripped,
        # so a path that itself contains escapes cannot spoof the terminal.
        header = f"{_CONTROL_CHARS.sub('', show_file)}:"
        body = "\n".join(
            [header, *(f"  {line}" for line in cls._read_show_file(show_file))]
        )
        return f"{text}\n\n{body}"

    @staticmethod
    def _prompt(message: str, options: list[str]) -> str:
        """Display the gate message and prompt for a choice.

        ``message`` may span multiple lines (e.g. when review material has
        been folded in); each line is rendered inside the gate box.
        """
        print("\n  β”Œβ”€ Gate ─────────────────────────────────────")
        for line in message.split("\n"):
            print(f"  β”‚ {line}" if line else "  β”‚")
        print("  β”‚")
        for i, opt in enumerate(options, 1):
            print(f"  β”‚  [{i}] {opt}")
        print("  └────────────────────────────────────────────")

        while True:
            try:
                raw = input(f"  Choose [1-{len(options)}]: ").strip()
            except KeyboardInterrupt:
                # Ctrl+C is not a gate verdict at all. ``WorkflowEngine.execute``
                # and ``WorkflowEngine.resume`` turn a propagated
                # KeyboardInterrupt into ``RunStatus.PAUSED`` plus a
                # ``workflow_interrupted`` log event, so the operator can pick
                # the run back up with ``specify workflow resume``. Swallowing it here produced a
                # *decision* instead -- ``on_reject`` then fired, usually
                # aborting the whole run -- which is the one outcome an
                # interrupted reviewer did not choose. Re-raise so the gate
                # behaves like every other step under Ctrl+C.
                print()
                raise
            except EOFError:
                # EOF is different: stdin is closed, so there is no operator to
                # resume and pausing would strand the run. Fall back to a
                # rejection, which is the safe verdict for an unanswered review.
                #
                # ``options[-1]`` assumed the reject option is last, but
                # ``validate`` only requires that *some* option is
                # 'reject'/'abort' -- never that it is last. So
                # ``options: [approve, reject, request-changes]`` validated
                # clean and EOF resolved to 'request-changes', which
                # ``execute`` does not classify as a rejection: the gate
                # reported COMPLETED and the run walked past the human review.
                # Prefer the declared reject/abort option; for the documented
                # default ``[approve, reject]`` this is the previous behaviour.
                print()
                return next(
                    (o for o in options if o.lower() in ("reject", "abort")),
                    options[-1],
                )
            # isdecimal() (not isdigit()): int() accepts exactly the decimal-digit
            # set, whereas isdigit() also returns True for superscripts/subscripts
            # (e.g. "Β²") that int() then rejects with ValueError β€” crashing
            # this interactive loop.
            if raw.isdecimal() and 1 <= int(raw) <= len(options):
                return options[int(raw) - 1]
            # Also accept the option name directly
            if raw.lower() in [o.lower() for o in options]:
                return next(o for o in options if o.lower() == raw.lower())
            print(f"  Invalid choice. Enter 1-{len(options)} or an option name.")

    @staticmethod
    def _read_show_file(show_file: str) -> list[str]:
        """Return the lines of ``show_file`` for display.

        Reads at most ``MAX_SHOW_FILE_LINES`` lines so a large file cannot
        flood the prompt, and returns a short notice instead of raising
        when the file is missing, undecodable, or names an invalid path,
        so a misconfigured ``show_file`` never breaks the interactive
        prompt. ``ValueError`` covers paths the OS rejects outright (e.g.
        an embedded NUL byte), which ``Path.open`` raises before any I/O.

        Control characters are stripped from each line so file content
        cannot inject ANSI escape sequences into the terminal.
        """
        lines: list[str] = []
        truncated = False
        try:
            with Path(show_file).open(encoding="utf-8") as handle:
                for line in handle:
                    if len(lines) >= GateStep.MAX_SHOW_FILE_LINES:
                        truncated = True
                        break
                    lines.append(_CONTROL_CHARS.sub("", line.rstrip("\n")))
        except (OSError, UnicodeDecodeError, ValueError) as exc:
            # ``exc`` echoes the (possibly hostile) path, so strip it too.
            return [_CONTROL_CHARS.sub("", f"(could not read file: {exc})")]
        if not lines and not truncated:
            return ["(file is empty)"]
        if truncated:
            lines.append(
                f"… (output truncated at {GateStep.MAX_SHOW_FILE_LINES} lines)"
            )
        return lines

    def validate(self, config: dict[str, Any]) -> list[str]:
        errors = super().validate(config)
        if "message" not in config:
            errors.append(
                f"Gate step {config.get('id', '?')!r} is missing 'message' field."
            )
        options = config.get("options", ["approve", "reject"])
        if not isinstance(options, list) or not options:
            errors.append(
                f"Gate step {config.get('id', '?')!r}: 'options' must be a non-empty list."
            )
        elif not all(isinstance(o, str) for o in options):
            errors.append(
                f"Gate step {config.get('id', '?')!r}: all options must be strings."
            )
        on_reject = config.get("on_reject", "abort")
        if on_reject not in ("abort", "skip", "retry"):
            errors.append(
                f"Gate step {config.get('id', '?')!r}: 'on_reject' must be "
                f"'abort', 'skip', or 'retry'."
            )
        if "verdict_input" in config and (
            not isinstance(config["verdict_input"], str) or not config["verdict_input"]
        ):
            errors.append(
                f"Gate step {config.get('id', '?')!r}: 'verdict_input' must be "
                "a non-empty string."
            )
        # Only inspect option text when every option is a string; otherwise the
        # `o.lower()` below would raise AttributeError on a non-string option
        # (already reported above) and break validate_workflow's never-raise contract.
        if (
            on_reject in ("abort", "retry")
            and isinstance(options, list)
            and all(isinstance(o, str) for o in options)
        ):
            reject_choices = {"reject", "abort"}
            if not any(o.lower() in reject_choices for o in options):
                errors.append(
                    f"Gate step {config.get('id', '?')!r}: on_reject={on_reject!r} "
                    f"but options has no 'reject' or 'abort' choice."
                )
        return errors