Skip to content

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

feat: surface gate detail in the workflow run/resume --json payload (#2965)

Huy Dof5f76160a3c3
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 9a05b7e51..87d9a56cb 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -2099,13 +2099,85 @@ def _parse_input_values(input_values: list[str] | None) -> dict[str, Any]:
def _workflow_run_payload(state: Any) -> dict[str, Any]:
"""Machine-readable summary of a run/resume outcome."""
- return {
+ payload = {
"run_id": state.run_id,
"workflow_id": state.workflow_id,
"status": state.status.value,
"current_step_id": state.current_step_id,
"current_step_index": state.current_step_index,
}
+ gate = _gate_outcome(state)
+ if gate is not None:
+ payload["gate"] = gate
+ return payload
+
+
+def _is_gate_step(step: dict[str, Any]) -> bool:
+ """Whether a recorded step result is a gate.
+
+ Prefers the persisted ``type`` field, but when it is absent β€” a run paused
+ by an older version, whose step record predates ``type`` being stored β€”
+ falls back to the gate's unique output signature: only ``GateStep`` writes
+ an ``on_reject`` key. A record carrying a *different* known ``type`` is not
+ a gate, so the fallback applies only when ``type`` is missing entirely.
+ """
+ step_type = step.get("type")
+ if step_type == "gate":
+ return True
+ if step_type:
+ return False
+ output = step.get("output")
+ return isinstance(output, dict) and "on_reject" in output
+
+
+def _gate_outcome(state: Any) -> dict[str, Any] | None:
+ """Gate detail for the structured outcome, when the run rests at a gate.
+
+ A paused or gate-aborted run is otherwise indistinguishable from any
+ other pause/abort in the machine-readable payload; surfacing the gate's
+ prompt, options, and (after an interactive choice) the decision lets
+ orchestrators drive review gates without parsing the human-facing stream.
+ """
+ # Two run states rest *on* a gate: `paused` (awaiting a decision) and
+ # `aborted` (a gate rejected with `on_reject: abort` β€” the only path that
+ # sets ABORTED, leaving current_step_id on that gate). Any other status β€”
+ # notably `completed`/`failed` β€” must be suppressed: current_step_id is
+ # not cleared when a run whose last executed step was a gate moves on, so
+ # without this guard it would surface stale detail (run/resume/status).
+ if getattr(state.status, "value", state.status) not in ("paused", "aborted"):
+ return None
+ step = (getattr(state, "step_results", None) or {}).get(state.current_step_id)
+ if not isinstance(step, dict) or not _is_gate_step(step):
+ return None
+ output = step.get("output") or {}
+ # `message`, `options`, and `choice` may be non-string YAML literals in an
+ # unvalidated workflow (GateStep coerces none of them for the payload), so
+ # normalise all three for a stable JSON schema: message β†’ str, options β†’
+ # list[str] | None, choice β†’ str | None (None means no decision yet).
+ message = output.get("message")
+ choice = output.get("choice")
+ return {
+ "step_id": state.current_step_id,
+ "message": None if message is None else str(message),
+ "options": _normalize_gate_options(output.get("options")),
+ "choice": None if choice is None else str(choice),
+ }
+
+
+def _normalize_gate_options(options: Any) -> list[str] | None:
+ """Normalise a gate's ``options`` to a stable ``list[str]`` (or ``None``).
+
+ A valid gate stores a list, but an unvalidated workflow could leave a
+ scalar or tuple. ``None`` stays ``None`` (no options); a list/tuple maps
+ each element through ``str``; any other scalar becomes a single-element
+ list β€” so the emitted JSON schema is always ``list[str] | None``. A bare
+ string is treated as one option, never iterated character-by-character.
+ """
+ if options is None:
+ return None
+ if isinstance(options, (list, tuple)):
+ return [str(o) for o in options]
+ return [str(options)]
def _run_outcome_exit_code(status_value: str) -> int:
diff --git a/src/specify_cli/workflows/base.py b/src/specify_cli/workflows/base.py
index b144ca903..b61fdb1a0 100644
--- a/src/specify_cli/workflows/base.py
+++ b/src/specify_cli/workflows/base.py
@@ -47,9 +47,10 @@ class StepContext:
#: Resolved workflow inputs (from user prompts / defaults).
inputs: dict[str, Any] = field(default_factory=dict)
- #: Accumulated step results keyed by step ID.
- #: Each entry is ``{"integration": ..., "model": ..., "options": ...,
- #: "input": ..., "output": ...}``.
+ #: Accumulated step results keyed by step ID. Each entry is the dict the
+ #: engine persists per step:
+ #: ``{"type": ..., "integration": ..., "model": ..., "options": ...,
+ #: "input": ..., "output": ..., "status": ...}``.
steps: dict[str, dict[str, Any]] = field(default_factory=dict)
#: Current fan-out item (set only inside fan-out iterations).
diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index 0d56f7df7..f463bc66c 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -676,6 +676,7 @@ class WorkflowEngine:
# Record step results β€” prefer resolved values from step output
step_data = {
+ "type": step_type,
"integration": result.output.get("integration")
or step_config.get("integration")
or context.default_integration,
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index a87c09cf0..8cbd4a6e8 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -5341,3 +5341,234 @@ steps:
assert resumed.exit_code == 1, resumed.stdout
payload = _json.loads(resumed.stdout)
assert payload["status"] == "failed"
+
+
+class TestWorkflowRunGateOutcomeJson:
+ """CLI-level tests: the --json payload surfaces gate pauses."""
+
+ _WF_GATE = """
+schema_version: "1.0"
+workflow:
+ id: "gate-json"
+ name: "Gate JSON"
+ version: "1.0.0"
+steps:
+ - id: review
+ type: gate
+ message: "Approve the thing?"
+ options: ["approve", "reject"]
+"""
+
+ _WF_PLAIN = """
+schema_version: "1.0"
+workflow:
+ id: "plain-json"
+ name: "Plain JSON"
+ version: "1.0.0"
+steps:
+ - id: fine
+ type: shell
+ run: "exit 0"
+"""
+
+ def _run_json(self, tmp_path, monkeypatch, content, *, expected_exit=0):
+ import json as _json
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ path = tmp_path / "wf.yml"
+ path.write_text(content, encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ result = CliRunner().invoke(app, ["workflow", "run", str(path), "--json"])
+ # Assert the expected exit code before parsing so a real failure
+ # surfaces the actual output instead of an opaque JSON decode error.
+ # A terminal run still emits its JSON payload, then exits non-zero on
+ # ``failed``/``aborted`` (see ``_run_outcome_exit_code``), so callers
+ # pass the expected code. Use ``result.output`` for the message:
+ # under ``--json`` step output is redirected off stdout, so the useful
+ # diagnostics live there.
+ assert result.exit_code == expected_exit, result.output
+ return _json.loads(result.stdout)
+
+ def test_gate_pause_carries_gate_block(self, tmp_path, monkeypatch):
+ # CliRunner stdin is not a TTY, so the gate pauses for resume.
+ payload = self._run_json(tmp_path, monkeypatch, self._WF_GATE)
+ assert payload["status"] == "paused"
+ assert payload["gate"] == {
+ "step_id": "review",
+ "message": "Approve the thing?",
+ "options": ["approve", "reject"],
+ "choice": None,
+ }
+
+ def test_completed_run_has_no_gate_block(self, tmp_path, monkeypatch):
+ payload = self._run_json(tmp_path, monkeypatch, self._WF_PLAIN)
+ assert payload["status"] == "completed"
+ assert "gate" not in payload
+
+ def test_gate_abort_carries_gate_block(self, tmp_path, monkeypatch):
+ # An interactive gate the operator rejects ends the run as `aborted`
+ # (on_reject defaults to abort), not `paused`. The JSON surface must
+ # still carry the gate block with the recorded choice so an
+ # orchestrator can see *why* the run stopped. A gate abort emits the
+ # payload and then exits non-zero (aborted β†’ exit 1), so the helper
+ # is told to expect exit code 1.
+ from specify_cli.workflows.steps.gate import GateStep
+
+ _force_gate_stdin(monkeypatch, tty=True)
+ monkeypatch.setattr(
+ GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
+ )
+ payload = self._run_json(
+ tmp_path, monkeypatch, self._WF_GATE, expected_exit=1
+ )
+ assert payload["status"] == "aborted"
+ assert payload["gate"] == {
+ "step_id": "review",
+ "message": "Approve the thing?",
+ "options": ["approve", "reject"],
+ "choice": "reject",
+ }
+
+ def test_gate_block_emitted_only_when_run_rests_at_gate(self):
+ # A run rests *on* a gate only while `paused` (awaiting a decision) or
+ # `aborted` (gate rejected with on_reject: abort). current_step_id is
+ # not cleared afterwards, so a `completed`/`failed` run whose last
+ # executed step was a gate must NOT surface a stale gate block.
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ gate_step = {
+ "type": "gate",
+ "output": {
+ "message": "m",
+ "options": ["approve", "reject"],
+ "choice": "reject",
+ },
+ }
+
+ def _state(status):
+ return SimpleNamespace(
+ status=SimpleNamespace(value=status),
+ current_step_id="review",
+ step_results={"review": gate_step},
+ )
+
+ assert _gate_outcome(_state("completed")) is None
+ assert _gate_outcome(_state("failed")) is None
+ assert _gate_outcome(_state("paused")) is not None
+ assert _gate_outcome(_state("aborted")) is not None
+
+ def test_gate_block_message_coerced_to_string(self):
+ # message may be a non-string YAML literal (e.g. a number); the JSON
+ # surface normalises it so the emitted schema stays stable.
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {"message": 12.5, "options": ["ok"], "choice": None},
+ }
+ },
+ )
+ assert _gate_outcome(state)["message"] == "12.5"
+
+ def test_gate_block_options_coerced_to_strings(self):
+ # options may be non-string / non-list literals in an unvalidated
+ # workflow; the JSON surface always normalises them to list[str] | None
+ # so the emitted schema is stable regardless of the input shape.
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ def _options_payload(options):
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {
+ "message": "m",
+ "options": options,
+ "choice": None,
+ },
+ }
+ },
+ )
+ return _gate_outcome(state)["options"]
+
+ assert _options_payload([1, 2.5]) == ["1", "2.5"] # list
+ assert _options_payload(("approve", "reject")) == ["approve", "reject"] # tuple
+ assert _options_payload("approve") == ["approve"] # bare scalar, not iterated
+ assert _options_payload(7) == ["7"] # numeric scalar
+ assert _options_payload(None) is None # absent stays absent
+
+ def test_gate_block_choice_coerced_to_string(self):
+ # An unvalidated gate can record a non-string choice; the JSON
+ # surface normalises it to str (and keeps None = no decision yet),
+ # consistent with the message/options normalization.
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ def _choice_payload(choice):
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {"message": "m", "options": ["ok"], "choice": choice},
+ }
+ },
+ )
+ return _gate_outcome(state)["choice"]
+
+ assert _choice_payload(None) is None # no decision yet
+ assert _choice_payload("reject") == "reject" # normal string passes through
+ assert _choice_payload(2) == "2" # non-string coerced
+
+ def test_gate_block_detected_without_type_field(self):
+ # A run paused by an older version has no persisted step `type`. The
+ # gate is still detected by its unique output signature (`on_reject`),
+ # so resume surfaces the gate block instead of silently dropping it.
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ # no "type" key β€” pre-dates the field being persisted
+ "output": {
+ "message": "Approve?",
+ "options": ["approve", "reject"],
+ "on_reject": "abort",
+ "choice": None,
+ },
+ }
+ },
+ )
+ gate = _gate_outcome(state)
+ assert gate is not None
+ assert gate["step_id"] == "review"
+ assert gate["options"] == ["approve", "reject"]
+
+ def test_non_gate_step_without_type_is_not_a_gate(self):
+ # A typeless record lacking the gate signature must NOT be mistaken for
+ # a gate (the fallback keys off `on_reject`, which only GateStep writes).
+ from types import SimpleNamespace
+ from specify_cli import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="run-tests",
+ step_results={
+ "run-tests": {"output": {"exit_code": 0, "stdout": "ok"}},
+ },
+ )
+ assert _gate_outcome(state) is None