π« Toolkit to help you get started with SDD or any other process!
"""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