Skip to content

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

7.8 KB
Raw Blame
"""Shell step β€” run a local shell command."""

from __future__ import annotations

import io
import json
import locale
import math
import os
import subprocess
from typing import Any

from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
from specify_cli.workflows.expressions import evaluate_expression


class ShellStep(StepBase):
    """Run a local shell command (non-agent).

    Captures exit code and stdout/stderr.
    """

    type_key = "shell"

    def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
        run_cmd = config.get("run", "")
        if isinstance(run_cmd, str) and "{{" in run_cmd:
            run_cmd = evaluate_expression(run_cmd, context)
        run_cmd = str(run_cmd)

        cwd = context.project_root or "."
        # 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)
        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"},
            )

        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
        # before use (see PUBLISHING.md for security guidance).
        try:
            proc = subprocess.run(  # noqa: S602 -- intentional shell=True (see NOTE above)
                run_cmd,
                shell=True,
                capture_output=True,
                cwd=cwd,
                env=env,
                timeout=timeout,
            )
            # Decode in this thread so malformed output becomes a step
            # failure on Windows too, where subprocess uses reader threads.
            # Preserve text=True's locale encoding and universal newlines.
            output = {"exit_code": proc.returncode, "stdout": "", "stderr": ""}
            encoding = locale.getpreferredencoding(False)
            decode_errors = []
            for name in ("stdout", "stderr"):
                try:
                    with io.TextIOWrapper(io.BytesIO(getattr(proc, name)), encoding=encoding) as stream:
                        output[name] = stream.read()
                except UnicodeDecodeError as exc:
                    decode_errors.append(f"Shell command {name} could not be decoded: {exc}")
            if decode_errors:
                return StepResult(
                    status=StepStatus.FAILED,
                    error="; ".join(decode_errors),
                    output=output,
                )
            if proc.returncode != 0:
                return StepResult(
                    status=StepStatus.FAILED,
                    error=f"Shell command exited with code {proc.returncode}.",
                    output=output,
                )
            if config.get("output_format") == "json":
                # Opt-in structured output: expose the parsed stdout under
                # ``output.data`` so later steps can consume typed values
                # (e.g. a fan-out's ``items:``). A parse failure fails the
                # step β€” declaring ``output_format: json`` is a contract.
                try:
                    output["data"] = json.loads(output["stdout"])
                except json.JSONDecodeError as exc:
                    return StepResult(
                        status=StepStatus.FAILED,
                        error=(
                            f"Shell step {config.get('id', '?')!r} declared "
                            f"output_format: json but stdout is not valid "
                            f"JSON: {exc}"
                        ),
                        output=output,
                    )
            return StepResult(
                status=StepStatus.COMPLETED,
                output=output,
            )
        except subprocess.TimeoutExpired:
            return StepResult(
                status=StepStatus.FAILED,
                error=f"Shell command timed out after {timeout} seconds.",
                output={"exit_code": -1, "stdout": "", "stderr": "timeout"},
            )
        except OSError as exc:
            return StepResult(
                status=StepStatus.FAILED,
                error=f"Shell command failed: {exc}",
                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"]
        try:
            invalid_timeout = (
                isinstance(timeout, bool)
                or not isinstance(timeout, (int, float))
                or not math.isfinite(timeout)
                or timeout <= 0
            )
        except OverflowError:
            # An int too large to convert to float (e.g. a 400-digit YAML
            # scalar) is not a bool and *is* an int, so it clears every clause
            # before ``isfinite()`` and raises there β€” and would raise the same
            # from subprocess.run(timeout=...). Mirrors the prompt step.
            invalid_timeout = True
        if invalid_timeout:
            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:
            errors.append(
                f"Shell step {config.get('id', '?')!r} is missing 'run' field."
            )
        elif not isinstance(config["run"], str):
            # execute() str()-coerces run and invokes it under shell=True, so a
            # null or list 'run' would run the Python repr ('None', "['echo']")
            # as a command. Reject non-strings at validation, mirroring the
            # command-step input/options and gate options type checks. An
            # expression like "{{ ... }}" is still a str, so it stays valid.
            errors.append(
                f"Shell step {config.get('id', '?')!r}: 'run' must be a string, "
                f"got {type(config['run']).__name__}."
            )
        output_format = config.get("output_format")
        if output_format is not None and output_format != "json":
            errors.append(
                f"Shell step {config.get('id', '?')!r}: 'output_format' must "
                f"be 'json' when present, got {output_format!r}."
            )
        timeout_error = self._timeout_error(config)
        if timeout_error is not None:
            errors.append(timeout_error)
        return errors