💫 Toolkit to help you get started with SDD or any other process!
feat(workflows): expose workflow source directory to steps (#3469)
Roland Huss6688b447b72d
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex 8bd4a8778..1dfc5e690 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -305,6 +305,8 @@ Steps can reference inputs and previous step outputs using `{{ expression }}` sy| `inputs.spec` | Workflow input values || `steps.specify.output.file` | Output from a previous step || `item` | Current item in a fan-out iteration |+| `context.run_id` | Current workflow run ID |+| `context.workflow_dir` | Resolved absolute path to the workflow source directory. Empty string for string-loaded workflows. |Available filters: `default`, `join`, `contains`, `map`, `from_json`.@@ -316,6 +318,14 @@ args: "{{ inputs.spec }}"message: "{{ status | default('pending') }}"```+## Shell Step Environment Variables++Shell steps automatically receive the following environment variables:++| Variable | Description |+| -------- | ----------- |+| `SPECKIT_WORKFLOW_DIR` | Resolved absolute path to the workflow source directory (same value as `{{ context.workflow_dir }}`). Not set when the workflow has no source path. |+## Input Types| Type | Coercion |diff --git a/src/specify_cli/workflows/base.py b/src/specify_cli/workflows/base.pyindex 3a4267930..6ad14cc25 100644--- a/src/specify_cli/workflows/base.py+++ b/src/specify_cli/workflows/base.py@@ -74,6 +74,9 @@ class StepContext:#: Current run ID.run_id: str | None = None+ #: Source directory of the workflow definition file.+ workflow_dir: str | None = None+@dataclassclass StepResult:diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.pyindex 0c2a06f77..91a9ac2ad 100644--- a/src/specify_cli/workflows/engine.py+++ b/src/specify_cli/workflows/engine.py@@ -508,6 +508,7 @@ class RunState:# append_log is never called while _lock is held, the two never nest.self._log_lock = threading.Lock()self.inputs: dict[str, Any] = {}+ self.workflow_dir: str | None = Noneself.created_at = datetime.now(timezone.utc).isoformat()self.updated_at = self.created_atself.log_entries: list[dict[str, Any]] = []@@ -562,6 +563,7 @@ class RunState:"current_step_index": self.current_step_index,"current_step_id": self.current_step_id,"step_results": self.step_results,+ "workflow_dir": self.workflow_dir,"created_at": self.created_at,"updated_at": self.updated_at,}@@ -654,6 +656,7 @@ class RunState:state.current_step_index = state_data.get("current_step_index", 0)state.current_step_id = state_data.get("current_step_id")state.step_results = state_data.get("step_results", {})+ state.workflow_dir = state_data.get("workflow_dir")state.created_at = state_data.get("created_at", "")state.updated_at = state_data.get("updated_at", "")@@ -810,6 +813,12 @@ class WorkflowEngine:# Resolve inputsresolved_inputs = self._resolve_inputs(definition, inputs or {})state.inputs = resolved_inputs+ workflow_dir = (+ str(definition.source_path.resolve().parent)+ if definition.source_path is not None+ else None+ )+ state.workflow_dir = workflow_dirstate.status = RunStatus.RUNNINGstate.save()@@ -820,6 +829,7 @@ class WorkflowEngine:default_options=definition.default_options,project_root=str(self.project_root),run_id=state.run_id,+ workflow_dir=workflow_dir,)# Execute steps@@ -885,6 +895,7 @@ class WorkflowEngine:default_options=definition.default_options,project_root=str(self.project_root),run_id=state.run_id,+ workflow_dir=state.workflow_dir,)from . import STEP_REGISTRYdiff --git a/src/specify_cli/workflows/expressions.py b/src/specify_cli/workflows/expressions.pyindex 9953f5ff6..0df1ee617 100644--- a/src/specify_cli/workflows/expressions.py+++ b/src/specify_cli/workflows/expressions.py@@ -142,7 +142,8 @@ def _build_namespace(context: Any) -> dict[str, Any]:# 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}+ workflow_dir = getattr(context, "workflow_dir", None) or ""+ ns["context"] = {"run_id": run_id, "workflow_dir": workflow_dir}return nsdiff --git a/src/specify_cli/workflows/steps/shell/__init__.py b/src/specify_cli/workflows/steps/shell/__init__.pyindex 9faac62e4..fb19c33fc 100644--- a/src/specify_cli/workflows/steps/shell/__init__.py+++ b/src/specify_cli/workflows/steps/shell/__init__.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport jsonimport math+import osimport subprocessfrom typing import Any@@ -40,6 +41,13 @@ class ShellStep(StepBase):error=timeout_error,output={"exit_code": -1, "stdout": "", "stderr": "invalid timeout"},)++ env = {**os.environ}+ if context.workflow_dir:+ env["SPECKIT_WORKFLOW_DIR"] = context.workflow_dir+ else:+ env.pop("SPECKIT_WORKFLOW_DIR", None)+# NOTE: shell=True is required to support pipes, redirects, and# multi-command expressions in workflow YAML. Workflow authors# control commands; catalog-installed workflows should be reviewed@@ -51,6 +59,7 @@ class ShellStep(StepBase):capture_output=True,text=True,cwd=cwd,+ env=env,timeout=timeout,)output = {diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 468aad53b..8162c150c 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -4516,6 +4516,286 @@ steps:assert state.step_results["stamp"]["output"]["stdout"].strip() == "explicit-456"+# ===== context.workflow_dir Tests =====+++class TestContextWorkflowDir:+ """Tests for `{{ context.workflow_dir }}` and `SPECKIT_WORKFLOW_DIR`."""++ def test_context_workflow_dir_resolves(self):+ """``{{ context.workflow_dir }}`` resolves to ``StepContext.workflow_dir``."""+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(workflow_dir="/home/user/my-workflow")+ assert evaluate_expression("{{ context.workflow_dir }}", ctx) == "/home/user/my-workflow"++ def test_context_workflow_dir_defaults_to_empty_when_unset(self):+ """``{{ context.workflow_dir }}`` resolves to ``""`` when no source+ path is available (string-loaded workflows, dry-run).+ """+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext()+ assert evaluate_expression("{{ context.workflow_dir }}", ctx) == ""++ def test_context_workflow_dir_string_interpolation(self):+ """Workflow dir interpolates inside a larger template string."""+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(workflow_dir="/opt/workflows/setup")+ result = evaluate_expression("cp {{ context.workflow_dir }}/config.yml .", ctx)+ assert result == "cp /opt/workflows/setup/config.yml ."++ def test_step_context_workflow_dir(self):+ """StepContext accepts and stores workflow_dir."""+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(workflow_dir="/some/path")+ assert ctx.workflow_dir == "/some/path"++ ctx_none = StepContext()+ assert ctx_none.workflow_dir is None++ def test_from_yaml_sets_workflow_dir(self, project_dir):+ """Workflow loaded from a YAML file has workflow_dir set to the+ file's parent directory.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine++ wf_dir = project_dir / "my-workflows"+ wf_dir.mkdir()+ wf_file = wf_dir / "setup.yml"+ wf_file.write_text("""+schema_version: "1.0"+workflow:+ id: "from-yaml"+ name: "From YAML"+ version: "1.0.0"+steps:+ - id: check-dir+ type: shell+ run: "echo DIR={{ context.workflow_dir }}"+""")+ definition = WorkflowDefinition.from_yaml(wf_file)+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ stdout = state.step_results["check-dir"]["output"]["stdout"]+ assert stdout.strip() == f"DIR={wf_dir.resolve()}"++ def test_from_string_has_empty_workflow_dir(self, project_dir):+ """String-loaded workflows have empty workflow_dir."""+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine++ definition = WorkflowDefinition.from_string("""+schema_version: "1.0"+workflow:+ id: "from-string"+ name: "From String"+ version: "1.0.0"+steps:+ - id: check-dir+ type: shell+ run: "echo DIR={{ context.workflow_dir }}"+""")+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ stdout = state.step_results["check-dir"]["output"]["stdout"]+ assert stdout.strip() == "DIR="++ def test_shell_step_receives_speckit_workflow_dir_env_var(self, project_dir):+ """Shell steps receive SPECKIT_WORKFLOW_DIR in their environment."""+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ import sys++ wf_dir = project_dir / "wf"+ wf_dir.mkdir()+ wf_file = wf_dir / "workflow.yml"+ python = sys.executable.replace("\\", "/")+ wf_file.write_text(f"""+schema_version: "1.0"+workflow:+ id: "env-var-test"+ name: "Env Var Test"+ version: "1.0.0"+steps:+ - id: print-env+ type: shell+ run: '"{python}" -c "import os; print(os.environ.get(''SPECKIT_WORKFLOW_DIR'', ''UNSET''))"'+""")+ definition = WorkflowDefinition.from_yaml(wf_file)+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ stdout = state.step_results["print-env"]["output"]["stdout"]+ assert stdout.strip() == str(wf_dir.resolve())++ def test_shell_step_no_env_var_when_workflow_dir_unset(self, project_dir, monkeypatch):+ """Shell steps do not set SPECKIT_WORKFLOW_DIR for string-loaded workflows."""+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ import sys++ monkeypatch.delenv("SPECKIT_WORKFLOW_DIR", raising=False)++ python = sys.executable.replace("\\", "/")+ definition = WorkflowDefinition.from_string(f"""+schema_version: "1.0"+workflow:+ id: "no-env-var"+ name: "No Env Var"+ version: "1.0.0"+steps:+ - id: check-env+ type: shell+ run: '"{python}" -c "import os; print(os.environ.get(''SPECKIT_WORKFLOW_DIR'', ''UNSET''))"'+""")+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ stdout = state.step_results["check-env"]["output"]["stdout"]+ assert stdout.strip() == "UNSET"++ def test_resume_preserves_original_workflow_dir(self, project_dir):+ """Resumed workflow uses the original source directory, not the+ run-directory copy path.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ from specify_cli.workflows.base import RunStatus++ wf_dir = project_dir / "original-source"+ wf_dir.mkdir()+ wf_file = wf_dir / "resumable.yml"+ wf_file.write_text("""+schema_version: "1.0"+workflow:+ id: "resumable"+ name: "Resumable"+ version: "1.0.0"+steps:+ - id: gate-step+ type: gate+ message: "Approve?"+ - id: after-gate+ type: shell+ run: "echo DIR={{ context.workflow_dir }}"+""")+ definition = WorkflowDefinition.from_yaml(wf_file)+ engine = WorkflowEngine(project_dir)++ # Execute -- gate pauses the workflow+ state = engine.execute(definition)+ assert state.status == RunStatus.PAUSED+ assert state.workflow_dir == str(wf_dir.resolve())++ # Simulate gate approval by patching the gate step+ from unittest.mock import patch+ from specify_cli.workflows.base import StepResult++ with patch(+ "specify_cli.workflows.steps.gate.GateStep.execute",+ return_value=StepResult(output={"approved": True}),+ ):+ state = engine.resume(state.run_id)++ assert state.status == RunStatus.COMPLETED+ stdout = state.step_results["after-gate"]["output"]["stdout"]+ assert stdout.strip() == f"DIR={wf_dir.resolve()}"++ def test_workflow_dir_persisted_in_state(self, project_dir):+ """workflow_dir is persisted in state.json and survives load/save."""+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine, RunState++ wf_dir = project_dir / "persist-test"+ wf_dir.mkdir()+ wf_file = wf_dir / "workflow.yml"+ wf_file.write_text("""+schema_version: "1.0"+workflow:+ id: "persist-wfdir"+ name: "Persist WfDir"+ version: "1.0.0"+steps:+ - id: noop+ type: shell+ run: "echo ok"+""")+ definition = WorkflowDefinition.from_yaml(wf_file)+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)++ # Reload state from disk and verify workflow_dir survived+ loaded = RunState.load(state.run_id, project_dir)+ assert loaded.workflow_dir == str(wf_dir.resolve())++ def test_installed_workflow_has_workflow_dir(self, project_dir):+ """Installed-by-ID workflows get workflow_dir pointing to the+ installation directory (.specify/workflows/<id>/).+ """+ from specify_cli.workflows.engine import WorkflowEngine+ from specify_cli.workflows.base import RunStatus++ wf_id = "installed-wfdir"+ install_dir = project_dir / ".specify" / "workflows" / wf_id+ install_dir.mkdir(parents=True)+ (install_dir / "workflow.yml").write_text("""+schema_version: "1.0"+workflow:+ id: "installed-wfdir"+ name: "Installed WfDir"+ version: "1.0.0"+steps:+ - id: check-dir+ type: shell+ run: "echo DIR={{ context.workflow_dir }}"+""")+ engine = WorkflowEngine(project_dir)+ definition = engine.load_workflow(wf_id)+ state = engine.execute(definition)++ assert state.status == RunStatus.COMPLETED+ stdout = state.step_results["check-dir"]["output"]["stdout"]+ assert stdout.strip() == f"DIR={install_dir.resolve()}"++ def test_workflow_dir_is_resolved_to_absolute(self, project_dir):+ """workflow_dir is resolved to an absolute path even when the+ source path is relative.+ """+ from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine+ import os++ wf_dir = project_dir / "rel-test"+ wf_dir.mkdir()+ wf_file = wf_dir / "workflow.yml"+ wf_file.write_text("""+schema_version: "1.0"+workflow:+ id: "rel-path"+ name: "Relative Path"+ version: "1.0.0"+steps:+ - id: check+ type: shell+ run: "echo ok"+""")+ # Load via a relative path+ saved_cwd = os.getcwd()+ try:+ os.chdir(project_dir)+ rel_path = Path("rel-test/workflow.yml")+ definition = WorkflowDefinition.from_yaml(rel_path)+ engine = WorkflowEngine(project_dir)+ state = engine.execute(definition)+ finally:+ os.chdir(saved_cwd)++ assert Path(state.workflow_dir).is_absolute()+ assert state.workflow_dir == str(wf_dir.resolve())++# ===== continue_on_error Tests =====## Locks the contract documented in workflows/README.md "Error Handling"diff --git a/workflows/README.md b/workflows/README.mdindex 93b006ec5..888eac9de 100644--- a/workflows/README.md+++ b/workflows/README.md@@ -348,6 +348,7 @@ 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. |+| `context.workflow_dir` | The resolved absolute path to the directory containing the workflow source file. For file-loaded workflows this is the parent directory of the YAML file; for installed-by-ID workflows it is the absolute path to the installation directory (e.g. `<project>/.specify/workflows/<id>/`); for string-loaded workflows it is an empty string. On resume the original source directory is preserved from the first execution. |```yaml# Stamp telemetry events with the run id for cross-system join.@@ -365,6 +366,11 @@ current run:command: speckit.specifyinput:args: "{{ context.run_id }}"++# Reference a sibling file shipped alongside the workflow definition.+- id: apply-config+ type: shell+ run: 'cp "{{ context.workflow_dir }}/defaults.yml" ./config.yml'```## Input Types@@ -445,6 +451,7 @@ specify workflow catalog remove <index>| Variable | Description ||----------|-------------|| `SPECKIT_WORKFLOW_CATALOG_URL` | Override the catalog URL (replaces all defaults) |+| `SPECKIT_WORKFLOW_DIR` | Set automatically for shell steps; contains the resolved absolute path to the workflow source directory (same value as `{{ context.workflow_dir }}`). Not set when the workflow has no source path (string-loaded workflows). |## Configuration Files