feat(workflows): make shell step timeout configurable (#3327) (#3328)

* feat(workflows): make shell step timeout configurable (#3327)

The `shell` step hardcoded a 300s subprocess timeout, so any command
that legitimately runs longer than five minutes (a full build, a linter
aggregator, an integration-test target) was killed with TimeoutExpired
and failed the whole run, with no YAML knob to raise the limit.

Add an optional `timeout` field (seconds) that defaults to 300 for
backward compatibility and is threaded through to `subprocess.run`. The
timeout failure message now reports the configured value instead of a
hardcoded 300. `validate` rejects a `timeout` that is not a positive
number (bool is rejected explicitly, since it is an int subclass but a
config error rather than a duration).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* test(workflows): cover non-finite timeout rejection in shell step

The isfinite guard added in 955d46a rejects YAML .inf/.nan timeouts, but no test asserted it. inf and nan are floats that pass a plain > 0 check (nan <= 0 is False), so without an explicit case a regression could silently reaccept them and crash subprocess.run(timeout=...) at runtime. Addresses the remaining Copilot review comment on PR #3328.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(workflows): document configurable shell step timeout

Address Copilot review feedback on #3328: the per-step `timeout`
option was not reflected in the public workflow docs. The Shell Steps
section only showed `run:`, so readers couldn't discover `timeout:`,
its unit (seconds), or its default (300).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* refactor(workflows): consolidate shell-step timeout validation into one path

Address Copilot review feedback on #3328:

- Remove the dead "fall back to default" timeout block in execute(): it
  re-read `timeout` from config immediately after, so the fallback was
  discarded and its comment contradicted the new fail-on-invalid behavior.
- Extract a single `_timeout_error()` helper shared by execute() and
  validate() so both reject the same values with the same message, instead
  of two drifting copies of the check.
- Hoist the duplicated inline `import math` to module scope.
- Add test_execute_fails_cleanly_on_invalid_timeout: asserts execute()
  fails the step (rather than raising) on an unvalidated string/bool/inf/0
  timeout, covering the engine-skips-validate path Copilot flagged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

src/specify_cli/workflows/steps/shell/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import math
 import subprocess
 from typing import Any
 
@@ -25,15 +26,20 @@ class ShellStep(StepBase):
         run_cmd = str(run_cmd)
 
         cwd = context.project_root or "."
-        # Defensive: the engine does not auto-validate step config, so an
-        # invalid ``timeout`` (string, None, ...) would otherwise raise a
-        # TypeError from subprocess.run() and crash the whole run.  Mirror
-        # the engine's handling of unvalidated ``continue_on_error`` by
-        # only honoring well-formed values and falling back to the default.
+        # Per-step execution timeout in seconds; defaults to 300 for backward
+        # compatibility. The engine does not auto-validate step config, so
+        # validate here as well — a caller that skips WorkflowEngine.validate()
+        # must fail the step cleanly rather than crash subprocess.run() with a
+        # TypeError (or silently coerce ``timeout: true`` to a 1s duration,
+        # since bool is an int subclass).
         timeout = config.get("timeout", 300)
-        if isinstance(timeout, bool) or not isinstance(timeout, int) or timeout <= 0:
-            timeout = 300
-
+        timeout_error = self._timeout_error(config)
+        if timeout_error is not None:
+            return StepResult(
+                status=StepStatus.FAILED,
+                error=timeout_error,
+                output={"exit_code": -1, "stdout": "", "stderr": "invalid timeout"},
+            )
         # 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
@@ -92,6 +98,32 @@ class ShellStep(StepBase):
                 output={"exit_code": -1, "stdout": "", "stderr": str(exc)},
             )
 
+    @staticmethod
+    def _timeout_error(config: dict[str, Any]) -> str | None:
+        """Return an error message if ``config['timeout']`` is invalid, else None.
+
+        Shared by execute() and validate() so both paths reject the same
+        values with the same message. An absent ``timeout`` is valid (the
+        default is used). bool is a subclass of int, but ``timeout: true`` is a
+        config error rather than a duration, so it is rejected explicitly.
+        Non-finite floats (YAML ``.inf``/``.nan``) pass a plain ``> 0`` check
+        but would raise in subprocess.run(), so they are rejected too.
+        """
+        if "timeout" not in config:
+            return None
+        timeout = config["timeout"]
+        if (
+            isinstance(timeout, bool)
+            or not isinstance(timeout, (int, float))
+            or not math.isfinite(timeout)
+            or timeout <= 0
+        ):
+            return (
+                f"Shell step {config.get('id', '?')!r}: 'timeout' must be a "
+                f"positive number of seconds, got {timeout!r}."
+            )
+        return None
+
     def validate(self, config: dict[str, Any]) -> list[str]:
         errors = super().validate(config)
         if "run" not in config:
@@ -114,16 +146,7 @@ class ShellStep(StepBase):
                 f"Shell step {config.get('id', '?')!r}: 'output_format' must "
                 f"be 'json' when present, got {output_format!r}."
             )
-        if "timeout" in config:
-            timeout = config["timeout"]
-            # bool is an int subclass, so reject it explicitly.
-            if (
-                isinstance(timeout, bool)
-                or not isinstance(timeout, int)
-                or timeout <= 0
-            ):
-                errors.append(
-                    f"Shell step {config.get('id', '?')!r}: 'timeout' must be a "
-                    f"positive integer (seconds) when present, got {timeout!r}."
-                )
+        timeout_error = self._timeout_error(config)
+        if timeout_error is not None:
+            errors.append(timeout_error)
         return errors