π« Toolkit to help you get started with SDD or any other process!
feat(workflows): expose {{ context.run_id }} template variable (#2664)
Huy Doc6afe4cde12a
diff --git a/src/specify_cli/workflows/expressions.py b/src/specify_cli/workflows/expressions.pyindex eb39a31e7..3cc74c764 100644--- a/src/specify_cli/workflows/expressions.py+++ b/src/specify_cli/workflows/expressions.py@@ -102,6 +102,15 @@ def _build_namespace(context: Any) -> dict[str, Any]:ns["item"] = context.itemif hasattr(context, "fan_in"):ns["fan_in"] = context.fan_in or {}+ # Engine-managed runtime metadata. Always present (even outside a+ # run) so templates referencing it never error: `run_id` falls back+ # to an empty string when no run is active (dry-run, validation,+ # ad-hoc evaluator usage). The value is the same one Spec Kit+ # prints as `Run ID:` at the end of `workflow run` β auto-generated+ # runs use an 8-character uuid4 hex; operator-supplied ids may be+ # any alphanumeric string with hyphens or underscores.+ run_id = getattr(context, "run_id", None) or ""+ ns["context"] = {"run_id": run_id}return nsdiff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex bfd83a0de..114e6b02c 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -333,6 +333,44 @@ class TestExpressions:result = evaluate_expression("{{ steps.tasks.output.task_list[0].file }}", ctx)assert result == "a.md"+ def test_context_run_id_resolves(self):+ """``{{ context.run_id }}`` resolves to ``StepContext.run_id``.++ Locks the contract from issue #2590: workflow templates can+ reference the engine-assigned run id for telemetry, artifact+ metadata, or per-run scratch isolation.+ """+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(run_id="a1b2c3d4")+ assert evaluate_expression("{{ context.run_id }}", ctx) == "a1b2c3d4"++ def test_context_run_id_defaults_to_empty_when_unset(self):+ """``{{ context.run_id }}`` resolves to ``""`` when no run is+ active (dry-run, validation, ad-hoc evaluator usage) rather+ than raising β workflows referencing the variable never error+ outside a run context.+ """+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ # No run_id set on the context.+ ctx = StepContext()+ assert evaluate_expression("{{ context.run_id }}", ctx) == ""++ def test_context_run_id_string_interpolation(self):+ """Run id interpolates inside a larger template string β the+ common pattern for stamping shell commands and artifact paths+ with the run id.+ """+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(run_id="deadbeef")+ result = evaluate_expression("RUN_ID={{ context.run_id }}", ctx)+ assert result == "RUN_ID=deadbeef"+# ===== Integration Dispatch Tests =====@@ -2154,6 +2192,147 @@ steps:assert "retry-loop:step-b:2" in state.step_results+# ===== context.run_id Tests =====+#+# End-to-end coverage for the `{{ context.run_id }}` template+# variable introduced in issue #2590. Locks resolution inside the+# three step types the acceptance criteria called out β shell `run:`,+# command `input.args:`, and switch `expression:` β plus the+# "workflow doesn't reference it" backward-compat path.+++class TestContextRunId:+ """End-to-end tests for `{{ context.run_id }}` in workflow YAML."""++ def test_shell_run_resolves_run_id(self, project_dir):+ """`run: "echo {{ context.run_id }}"` substitutes the+ engine-assigned run id into the spawned shell, and the+ same value appears on `state.run_id`.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine++ definition = WorkflowDefinition.from_string("""+schema_version: "1.0"+workflow:+ id: "stamp-run-id"+ name: "Stamp Run Id"+ version: "1.0.0"+steps:+ - id: stamp+ type: shell+ run: "echo RUN_ID={{ context.run_id }}"+""")+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition, run_id="abc12345")++ assert state.run_id == "abc12345"+ stdout = state.step_results["stamp"]["output"]["stdout"]+ assert stdout.strip() == "RUN_ID=abc12345"++ def test_command_input_args_resolves_run_id(self, project_dir):+ """`input.args: "{{ context.run_id }}"` is resolved by+ `CommandStep` and recorded in step output, even when CLI+ dispatch is unavailable (no integration installed). Covers+ the artifact-metadata use case from the issue.+ """+ from unittest.mock import patch+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine++ definition = WorkflowDefinition.from_string("""+schema_version: "1.0"+workflow:+ id: "command-stamp"+ name: "Command Stamp"+ version: "1.0.0"+ integration: claude+steps:+ - id: tag-artifact+ command: speckit.specify+ input:+ args: "{{ context.run_id }}"+""")+ engine = WorkflowEngine(project_dir)+ with patch(+ "specify_cli.workflows.steps.command.shutil.which",+ return_value=None,+ ):+ state = engine.execute(definition, run_id="cafef00d")++ # Even when dispatch fails (no CLI), the resolved input is+ # recorded so downstream observers see the run id in artifact+ # metadata.+ assert state.step_results["tag-artifact"]["output"]["input"]["args"] == "cafef00d"++ def test_switch_expression_matches_on_run_id(self, project_dir):+ """`switch` over `{{ context.run_id }}` matches against case+ keys, and the nested branch can ALSO reference+ `{{ context.run_id }}`. Demonstrates the run id is a+ first-class value in the expression engine (not just a+ string-interpolation token) AND that it propagates into+ nested step execution via the recursive `_execute_steps`+ traversal.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ from specify_cli.workflows.base import RunStatus++ definition = WorkflowDefinition.from_string("""+schema_version: "1.0"+workflow:+ id: "switch-on-run-id"+ name: "Switch On Run Id"+ version: "1.0.0"+steps:+ - id: route+ type: switch+ expression: "{{ context.run_id }}"+ cases:+ target-run:+ - id: matched-branch+ type: shell+ run: "echo nested-run-id={{ context.run_id }}"+ default:+ - id: default-branch+ type: shell+ run: "echo defaulted"+""")+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition, run_id="target-run")++ assert state.status == RunStatus.COMPLETED+ assert state.step_results["route"]["output"]["matched_case"] == "target-run"+ assert "matched-branch" in state.step_results+ assert "default-branch" not in state.step_results+ # The nested branch sees the same run id β propagation through+ # recursive `_execute_steps` is intact.+ nested_stdout = state.step_results["matched-branch"]["output"]["stdout"]+ assert nested_stdout.strip() == "nested-run-id=target-run"++ def test_workflow_without_context_reference_unchanged(self, project_dir):+ """Workflows that do not reference `{{ context.run_id }}`+ continue to run exactly as before. Locks the byte-equivalent+ default required by the issue's acceptance criteria.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ from specify_cli.workflows.base import RunStatus++ definition = WorkflowDefinition.from_string("""+schema_version: "1.0"+workflow:+ id: "no-context-ref"+ name: "No Context Ref"+ version: "1.0.0"+steps:+ - id: only-step+ type: shell+ run: "echo hello"+""")+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ assert state.status == RunStatus.COMPLETED+ assert state.step_results["only-step"]["output"]["stdout"].strip() == "hello"++# ===== State Persistence Tests =====class TestRunState:diff --git a/workflows/README.md b/workflows/README.mdindex 31f736ff7..eb3d090ad 100644--- a/workflows/README.md+++ b/workflows/README.md@@ -239,6 +239,33 @@ message: "{{ status | default('pending') }}"Supported filters: `default`, `join`, `contains`, `map`.+### Runtime Context++`{{ context.* }}` exposes engine-managed runtime metadata for the+current run:++| Variable | Description |+|----------|-------------|+| `context.run_id` | The current workflow run id (the same value Spec Kit prints as `Run ID:` at the end of `workflow run`). Auto-generated runs are 8-character hex from `uuid4`; operator-supplied ids may be any alphanumeric string with hyphens or underscores. Empty string outside a run context. |++```yaml+# Stamp telemetry events with the run id for cross-system join.+- id: emit-event+ type: shell+ run: 'echo "{\"run_id\":\"{{ context.run_id }}\",\"event\":\"started\"}" >> events.jsonl'++# Per-run scratch directory.+- id: prep-scratch+ type: shell+ run: 'mkdir -p /tmp/run-{{ context.run_id }}'++# Pass run id into a command for artifact metadata.+- id: tag-artifact+ command: speckit.specify+ input:+ args: "{{ context.run_id }}"+```+## Input TypesWorkflow inputs are type-checked and coerced from CLI string values: