Skip to content

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

7.9 KB
Raw Blame
"""Command handler for ``specify workflow run``."""

from __future__ import annotations

from . import _command_run_ownership as run_ownership
from . import _commands as cli


@cli.workflow_app.command("run")
def workflow_run(
    source: str = cli.typer.Argument(..., help="Workflow ID or YAML file path"),
    input_values: list[str] | None = cli.typer.Option(
        None, "--input", "-i", help="Input values as key=value pairs"
    ),
    json_output: bool = cli.typer.Option(
        False,
        "--json",
        help="Emit the run outcome as a single JSON object instead of formatted text.",
    ),
):
    """Run a workflow from an installed ID or local YAML path."""
    from ..integrations.installer import IntegrationInstallError
    from . import load_custom_steps
    from .engine import WorkflowEngine

    source_path = cli.Path(source).expanduser()
    is_file_source = (
        source_path.suffix.lower() in (".yml", ".yaml") and source_path.is_file()
    )

    if is_file_source:
        # When running a YAML file directly, use cwd as project root without
        # requiring a .specify/ project directory β€” unless SPECIFY_INIT_DIR
        # explicitly names a project, in which case the strict override applies.
        override = cli._resolve_init_dir_override()
        project_root = override if override is not None else cli.Path.cwd()
        from .._project import (
            ProjectResolutionError,
            preflight_project_policy,
            render_project_error,
        )

        try:
            preflight_project_policy(project_root)
        except ProjectResolutionError as exc:
            render_project_error(exc)
        cli._reject_unsafe_workflow_storage(project_root)
    else:
        project_root = cli._require_specify_project(load_integrations=False)

    try:
        with cli._stdout_to_stderr_when(json_output):
            load_custom_steps(project_root)
            engine = WorkflowEngine(project_root)
            engine._load_integrations()
    except (IntegrationInstallError, OSError) as exc:
        cli._fail_integration_load(exc, json_output=json_output)
    if not json_output:
        # Escape the literal bracket (\[) so Rich renders `[<step id>]` instead
        # of parsing it as a style tag named after the step id -- which it
        # silently swallows (losing the only identifying content on the line),
        # applies as formatting when the id happens to be a real style such as
        # `bold`, or raises MarkupError when the id forms a closing tag (`/`),
        # failing the whole run. Escape the interpolated values too, since both
        # come from workflow YAML. Mirrors the `\[<type>]` step-graph precedent
        # in workflow_info below.
        engine.on_step_start = lambda sid, label: cli.console.print(
            f"  \u25b8 \\[{cli._escape_markup(str(sid))}] "
            f"{cli._escape_markup(str(label))} \u2026"
        )

    err = cli._error_console(json_output)

    registered_id: str | None = None
    registry_root = project_root
    if not is_file_source:
        # Reject path-equivalent spellings ("align-wf/", "align-wf/.") that
        # would miss the registry lookup yet still load the installed file,
        # bypassing the disabled check below.
        if (
            source in cli._RESERVED_WORKFLOW_IDS
            or not cli._WORKFLOW_ID_PATTERN.fullmatch(source)
        ):
            err.print(
                f"[red]Error:[/red] Invalid workflow ID: {cli._escape_markup(repr(source))}"
            )
            raise cli.typer.Exit(1)
        registered_id = source
    else:
        # A direct YAML path may still point at an installed workflow's own
        # file (lexically, or via a symlinked alias pointing into installed
        # storage); map it back to its owning project and ID so the
        # disabled check below can't be silently bypassed.
        owner_root, owner_id = run_ownership._resolve_installed_workflow_ownership(
            source_path, err
        )
        if owner_id is not None:
            registry_root = owner_root
            registered_id = owner_id

    if registered_id is not None:
        cli._require_enabled_workflow(registry_root, registered_id, err)

    try:
        definition = engine.load_workflow(source_path if is_file_source else source)
    except FileNotFoundError:
        err.print(f"[red]Error:[/red] Workflow not found: {source}")
        raise cli.typer.Exit(1)
    except ValueError as exc:
        err.print(f"[red]Error:[/red] Invalid workflow: {cli._escape_markup(str(exc))}")
        raise cli.typer.Exit(1)

    # Validate
    errors = engine.validate(definition)
    if errors:
        err.print("[red]Workflow validation failed:[/red]")
        for verr in errors:
            err.print(f"  β€’ {cli._escape_markup(str(verr))}")
        raise cli.typer.Exit(1)

    # Parse inputs
    inputs = cli._parse_input_values(input_values, json_output=json_output)

    if not json_output:
        cli.console.print(
            f"\n[bold cyan]Running workflow:[/bold cyan] {definition.name} ({definition.id})"
        )
        cli.console.print(f"[dim]Version: {definition.version}[/dim]\n")

    try:
        with cli._stdout_to_stderr_when(json_output):
            state = engine.execute(
                definition,
                inputs,
                installed_workflow_id=registered_id,
                # Only persist an explicit root when the installed workflow
                # genuinely belongs to a *different* project than the one
                # whose runs/ directory holds this run's own state (a
                # direct external workflow-file invocation) -- the common
                # case (an installed workflow run from its own project)
                # leaves this None so resume re-derives the owning root
                # from wherever the project currently is, transparently
                # surviving a project rename/move instead of baking in a
                # stale absolute path at run start.
                installed_registry_root=(
                    registry_root.resolve(strict=True)
                    if registered_id
                    and not run_ownership._same_existing_path(
                        registry_root, project_root
                    )
                    else None
                ),
            )
    except IntegrationInstallError as exc:
        execution_state = engine._execution_state.get()
        if execution_state is None:
            cli._fail_integration_load(exc, json_output=json_output)
        cli._fail_workflow_execution(exc, json_output=json_output, state=execution_state)
    except OSError as exc:
        cli._fail_workflow_execution(exc, json_output=json_output, state=engine._execution_state.get())
    except ValueError as exc:
        cli._fail_recorded_run(exc, json_output=json_output, state=engine._execution_state.get())
        err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
        raise cli.typer.Exit(1)
    except Exception as exc:
        cli._fail_recorded_run(exc, json_output=json_output, state=engine._execution_state.get())
        err.print(f"[red]Workflow failed:[/red] {cli._escape_markup(str(exc))}")
        raise cli.typer.Exit(1)

    if json_output:
        cli._emit_workflow_json(cli._workflow_run_payload(state))
        raise cli.typer.Exit(cli._run_outcome_exit_code(state.status.value))

    status_colors = {
        "completed": "green",
        "paused": "yellow",
        "failed": "red",
        "aborted": "red",
    }
    color = status_colors.get(state.status.value, "white")
    cli.console.print(f"\n[{color}]Status: {state.status.value}[/{color}]")
    cli.console.print(f"[dim]Run ID: {state.run_id}[/dim]")

    err_msg = cli._failed_step_error(state)
    if err_msg:
        cli.console.print(f"[red]Error:[/red] {cli._escape_markup(err_msg)}")

    if state.status.value == "paused":
        cli.console.print(
            f"\nResume with: [cyan]specify workflow resume {state.run_id}[/cyan]"
        )

    raise cli.typer.Exit(cli._run_outcome_exit_code(state.status.value))