π« Toolkit to help you get started with SDD or any other process!
"""Shared infrastructure and registration for ``specify workflow`` commands.
Decorated handlers live in command modules matching the CLI surface. Thin
forwarders preserve established direct-import and monkeypatch boundaries.
"""
from __future__ import annotations
import contextlib
import json
import os
import re
import sys
from pathlib import Path, PurePosixPath as PurePosixPath
from typing import Any
import typer
import yaml
from rich.markup import escape as _escape_markup
from .._console import console, err_console
from .._download_security import (
archive_format_from_content_type,
archive_format_from_name,
archive_suffix as archive_suffix,
detect_archive_format,
is_https_or_localhost_http,
is_safe_download_redirect,
read_response_limited,
safe_extract_archive,
)
from .._project import _resolve_init_dir_override as _resolve_init_dir_override
from ..shared_infra import verify_archive_sha256
workflow_app = typer.Typer(
name="workflow",
help="Manage and run automation workflows",
add_completion=False,
)
def _error_console(json_output: bool):
"""Console for error text: stderr under ``--json`` so the JSON stdout
stream stays parseable, the normal console otherwise. Mirrors the
stderr-only error routing already used by ``specify bundle``.
"""
return err_console if json_output else console
def _fail_integration_load(exc: Exception, *, json_output: bool, run_id: str | None = None):
"""Surface adapter failures before a workflow run state can be created."""
if json_output:
_emit_workflow_json({
"run_id": run_id,
"workflow_id": None,
"status": "failed",
"current_step_id": None,
"current_step_index": None,
"error": str(exc),
})
else:
console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
raise typer.Exit(1) from exc
def _fail_workflow_execution(
exc: Exception, *, json_output: bool, state: Any, resume: bool = False,
):
"""Report execution failures with the actual, context-local run state."""
if json_output:
payload = _workflow_run_payload(state) if state is not None else {
"run_id": None, "workflow_id": None,
"current_step_id": None, "current_step_index": None,
}
payload.update(status="failed", error=str(exc))
_emit_workflow_json(payload)
else:
label = "Resume failed" if resume else "Workflow failed"
console.print(f"[red]{label}:[/red] {_escape_markup(str(exc))}")
raise typer.Exit(1) from exc
def _fail_recorded_run(
exc: Exception, *, json_output: bool, state: Any, resume: bool = False,
) -> None:
"""Report *exc* as the run's outcome when the engine recorded it as one.
``WorkflowEngine.execute``/``resume`` persist an exception raised while
steps run (an expression error, say) as the run's ``failed`` status and
error, and mark that exception on the in-memory state, before re-raising
it. Errors raised before that point, such as input validation or a refused
resume, are not marked even when a loaded failed run carries the same
message, so this returns and the caller reports them as before.
"""
if state is not None and getattr(state, "_recorded_exception", None) is exc:
_fail_workflow_execution(
exc, json_output=json_output, state=state, resume=resume
)
def _open_workflow_registry(project_root: Path, out=None):
"""Construct a WorkflowRegistry, exiting cleanly on an unreadable file.
WorkflowRegistry fails closed (raises OSError) at construction when its
file can't be read, rather than falling back to an empty registry a
caller could mistake for "nothing installed". Every CLI command that
opens a registry needs this same clean-error boundary.
"""
from .catalog import WorkflowRegistry
try:
return WorkflowRegistry(project_root)
except OSError as exc:
(out or console).print(
f"[red]Error:[/red] Failed to read workflow registry: {_escape_markup(str(exc))}"
)
raise typer.Exit(1)
def _require_enabled_workflow(
registry_root: Path, workflow_id: str, out: Any
) -> bool:
"""Fail closed for corrupted or explicitly disabled registry entries."""
metadata = _open_workflow_registry(registry_root, out).get(workflow_id)
if metadata is not None and not isinstance(metadata, dict):
out.print(
f"[red]Error:[/red] Registry entry for "
f"'{_escape_markup(workflow_id)}' is corrupted"
)
raise typer.Exit(1)
if isinstance(metadata, dict) and not metadata.get("enabled", True):
out.print(
f"[red]Error:[/red] Workflow '{_escape_markup(workflow_id)}' is disabled. "
f"Enable with: specify workflow enable {_escape_markup(workflow_id)}"
)
raise typer.Exit(1)
return metadata is not None
def _resolve_run_owner_root(
installed_registry_root: str | None, project_root: Path
) -> Path:
"""Forward to the resume-private owner-state resolver."""
from ._command_resume_state import _resolve_run_owner_root as resolver
return resolver(installed_registry_root, project_root)
def _parse_input_values(
input_values: list[str] | None, *, json_output: bool = False
) -> dict[str, Any]:
"""Parse repeated ``key=value`` CLI inputs into a dict.
Shared by ``workflow run`` and ``workflow resume``. Exits with an error
on any entry missing ``=``.
"""
inputs: dict[str, Any] = {}
for kv in input_values or []:
if "=" not in kv:
_error_console(json_output).print(
f"[red]Error:[/red] Invalid input format: {kv!r} (expected key=value)"
)
raise typer.Exit(1)
key, _, value = kv.partition("=")
inputs[key.strip()] = value.strip()
return inputs
def _reject_unsafe_dir(path: Path, label: str) -> None:
"""Refuse to proceed when *path* is a symlink or an existing non-directory.
A symlinked ``.specify`` (or ``.specify/workflows``) could redirect
workflow writes outside the project root, so any command that creates or
writes files beneath it must bail first. Absence is tolerated β the caller
creates the directory β only an existing-but-wrong target is rejected.
"""
if path.is_symlink():
err_console.print(f"[red]Error:[/red] Refusing to use symlinked {label} path")
raise typer.Exit(1)
if path.exists() and not path.is_dir():
err_console.print(f"[red]Error:[/red] {label} path exists but is not a directory")
raise typer.Exit(1)
def _reject_unsafe_workflow_storage(project_root: Path) -> None:
"""Refuse symlinked workflow storage directories before workflow commands run."""
from ._storage import WorkflowStorageError, validate_workflow_storage
try:
validate_workflow_storage(project_root)
except WorkflowStorageError as exc:
err_console.print(f"[red]Error:[/red] {exc}")
raise typer.Exit(1) from exc
def _resolve_installed_workflow_ownership(
source_path: Path, err
) -> tuple[Path | None, str | None]:
"""Forward to the run-private installed-workflow ownership resolver."""
from ._command_run_ownership import (
_resolve_installed_workflow_ownership as resolver,
)
return resolver(source_path, err)
_WORKFLOW_ID_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")
_RESERVED_WORKFLOW_IDS: frozenset[str] = frozenset({"overlays", "runs", "steps"})
def _reject_insecure_download_redirect(old_url: str, new_url: str) -> None:
"""Reject insecure redirects before they are followed."""
import urllib.error
if is_safe_download_redirect(old_url, new_url):
return
raise urllib.error.URLError(
"redirect target must use HTTPS without entering a local target; "
"loopback HTTP may only redirect from another loopback URL"
)
# Workflow YAML definitions are small step/metadata text, not binaries, so
# this is generous headroom against a malicious or misbehaving server -- not
# a ceiling any legitimate workflow definition should ever approach.
_MAX_WORKFLOW_YAML_BYTES = 5 * 1024 * 1024 # 5 MiB
_DOWNLOAD_CHUNK_SIZE = 65536
def _read_response_within_limit(response, max_bytes: int | None = None) -> bytes:
"""Read *response* fully, enforcing *max_bytes* via bounded streaming.
A ``Content-Length`` header is checked up front to fail fast, but it is
never trusted alone: the actual bytes read are also counted as they
stream in, so a chunked or ``Content-Length``-less response that lies
about (or omits) its size still cannot exceed the limit.
``max_bytes`` defaults to ``None`` (resolved to the module-level
``_MAX_WORKFLOW_YAML_BYTES`` at call time, not at function-definition
time) so tests can override the effective limit via monkeypatching the
module attribute.
"""
if max_bytes is None:
max_bytes = _MAX_WORKFLOW_YAML_BYTES
content_length = None
getheader = getattr(response, "getheader", None)
if callable(getheader):
try:
raw_length = getheader("Content-Length")
except Exception:
raw_length = None
if raw_length is not None:
try:
content_length = int(raw_length)
except (TypeError, ValueError):
content_length = None
if content_length is not None and content_length > max_bytes:
raise ValueError(
f"response declared {content_length} bytes, exceeding the "
f"{max_bytes}-byte workflow size limit"
)
chunks: list[bytes] = []
total = 0
while True:
chunk = response.read(_DOWNLOAD_CHUNK_SIZE)
if not chunk:
break
total += len(chunk)
if total > max_bytes:
raise ValueError(f"response exceeds the {max_bytes}-byte workflow size limit")
chunks.append(chunk)
return b"".join(chunks)
def _workflow_yaml_is_declared(
source_name: str, content_type: str | None
) -> bool:
"""Return whether response metadata explicitly identifies workflow YAML."""
from urllib.parse import urlparse
path = urlparse(source_name).path.casefold()
media_type = (content_type or "").split(";", 1)[0].strip().casefold()
return path.endswith((".yml", ".yaml")) or media_type in {
"application/yaml",
"application/x-yaml",
"text/yaml",
"text/x-yaml",
}
def _sniff_workflow_archive_format(data: bytes):
"""Return a supported archive format when suffixless response bytes match."""
from io import BytesIO
try:
return detect_archive_format(
Path("workflow-download"),
archive_file=BytesIO(data),
)
except ValueError:
return None
def _enforce_workflow_yaml_size(data: bytes) -> None:
if len(data) > _MAX_WORKFLOW_YAML_BYTES:
raise ValueError(
f"response exceeds the {_MAX_WORKFLOW_YAML_BYTES}-byte workflow size limit"
)
def _validate_workflow_id_or_exit(workflow_id: str) -> None:
"""Validate that ``workflow_id`` is a safe installed-workflow directory name."""
if (
workflow_id in _RESERVED_WORKFLOW_IDS
or not _WORKFLOW_ID_PATTERN.fullmatch(workflow_id)
):
console.print(
f"[red]Error:[/red] Invalid workflow ID: {_escape_markup(repr(workflow_id))}"
)
raise typer.Exit(1)
def _safe_workflow_id_dir(workflows_dir: Path, workflow_id: str) -> Path:
"""Validate the per-id install directory before any write and return it.
Installs write to ``workflows_dir / <id> / workflow.yml``. The ``<id>``
segment comes from a workflow YAML or catalog key, so it must be checked
before ``mkdir``/copy/download follows a symlink outside the project root.
Rejects, with a clean ``typer.Exit``:
- an ``<id>`` that is a symlink or an existing non-directory
(the latter would otherwise make ``mkdir`` raise);
- an ``<id>`` that is not a single workflow-id path segment or collides
with internal workflow storage directories;
- an ``<id>`` that escapes ``workflows_dir`` (path traversal);
- an ``<id>/workflow.yml`` leaf that is a symlink or an existing
non-file (either would otherwise make the later write/copy raise).
The symlink/non-directory check runs *before* ``resolve()`` so a symlinked
``<id>`` reports as a symlink rather than misleadingly as path traversal.
``workflow_id`` is markup-escaped in output to avoid Rich markup injection.
"""
safe_id = _escape_markup(workflow_id)
_validate_workflow_id_or_exit(workflow_id)
dest_dir = workflows_dir / workflow_id
_reject_unsafe_dir(dest_dir, f".specify/workflows/{safe_id}")
try:
dest_dir.resolve().relative_to(workflows_dir.resolve())
except ValueError:
# Escape the repr (not the raw id) so backslashes added by repr cannot
# re-expose markup brackets to Rich.
console.print(
f"[red]Error:[/red] Invalid workflow ID: {_escape_markup(repr(workflow_id))}"
)
raise typer.Exit(1)
workflow_yml = dest_dir / "workflow.yml"
if workflow_yml.is_symlink():
console.print(
"[red]Error:[/red] Refusing to write through symlinked "
f".specify/workflows/{safe_id}/workflow.yml"
)
raise typer.Exit(1)
if workflow_yml.exists() and not workflow_yml.is_file():
console.print(
"[red]Error:[/red] "
f".specify/workflows/{safe_id}/workflow.yml exists but is not a file"
)
raise typer.Exit(1)
return dest_dir
class _StagedWorkflowFile:
"""Exclusive staging inode kept open until its atomic commit."""
def __init__(self, path: Path, fd: int) -> None:
self.path = path
self.fd = fd
def _write(self, chunks) -> None:
os.lseek(self.fd, 0, os.SEEK_SET)
os.ftruncate(self.fd, 0)
for chunk in chunks:
view = memoryview(chunk)
while view:
written = os.write(self.fd, view)
if written <= 0:
raise OSError("Failed to write staged workflow file")
view = view[written:]
def write_bytes(self, data: bytes) -> None:
self._write((data,))
def verify_path(self) -> None:
import stat
try:
path_stat = self.path.stat(follow_symlinks=False)
open_stat = os.fstat(self.fd)
except OSError as exc:
raise OSError(
"Staged workflow file changed before commit"
) from exc
if (
not stat.S_ISREG(path_stat.st_mode)
or path_stat.st_dev != open_stat.st_dev
or path_stat.st_ino != open_stat.st_ino
):
raise OSError("Staged workflow file changed before commit")
def set_mode(self, mode: int) -> None:
if hasattr(os, "fchmod"):
os.fchmod(self.fd, mode)
def close(self) -> None:
if self.fd < 0:
return
fd, self.fd = self.fd, -1
try:
os.close(fd)
except OSError:
pass
def _stage_workflow_file(
dest_dir: Path, *, use_project_file_mode: bool = False
) -> _StagedWorkflowFile:
"""Reserve a same-directory staging file so new/updated workflow.yml
content can be written and validated without ever touching (and risking
truncating) an existing destination file before the final atomic swap.
Shared by the local-install and catalog-install paths.
If dest_dir did not already exist, this call creates it; if mkstemp then
fails (disk full/EMFILE/quota), the freshly-created directory is removed
again via a guarded rmdir (never a broad rmtree, so any concurrently
written content is left untouched) before the original OSError is
re-raised unchanged. A pre-existing dest_dir (reinstall) is never
touched by this cleanup. For catalog-created files,
``use_project_file_mode`` recreates the reserved path exclusively with
mode 0666 so the process umask supplies the normal project-file mode.
The final descriptor remains open so callers write to and verify the
reserved inode rather than reopening a replaceable pathname."""
import tempfile
created_dir = not dest_dir.exists()
dest_dir.mkdir(parents=True, exist_ok=True)
fd = -1
staged_file: Path | None = None
try:
fd, tmp_name = tempfile.mkstemp(dir=dest_dir, prefix=".workflow.yml.", suffix=".tmp")
staged_file = Path(tmp_name)
if use_project_file_mode:
os.close(fd)
fd = -1
staged_file.unlink()
flags = os.O_RDWR | os.O_CREAT | os.O_EXCL
flags |= getattr(os, "O_NOFOLLOW", 0)
fd = os.open(staged_file, flags, 0o666)
except OSError:
if fd >= 0:
try:
os.close(fd)
except OSError:
pass
if staged_file is not None:
try:
staged_file.unlink(missing_ok=True)
except OSError:
pass
if created_dir:
try:
dest_dir.rmdir()
except OSError as cleanup_exc:
console.print(
"[yellow]Warning:[/yellow] Failed to remove incomplete "
f"workflow directory: {_escape_markup(str(cleanup_exc))}"
)
raise
assert staged_file is not None
return _StagedWorkflowFile(staged_file, fd)
@contextlib.contextmanager
def _workflow_install_transaction(project_root: Path):
"""Serialize workflow file swaps with their registry updates."""
from ..shared_infra import _exclusive_project_lock
with _exclusive_project_lock(
project_root, ".workflow-install.lock", context="workflow install"
):
yield
def _commit_workflow_file(
staged_file: Path | _StagedWorkflowFile,
dest_file: Path,
existed_before: bool,
) -> Path | None:
"""Atomically swap ``staged_file`` onto ``dest_file``. If a prior file
existed, it is first renamed to a unique sibling (path returned) so a
later failure (e.g. registry.add()) can restore it via rename instead
of a content rewrite -- the destination is never truncated/overwritten
in place. If the second rename fails after the first succeeded, the
prior file is put back immediately so dest_file is never left simply
missing."""
staged_path = (
staged_file.path
if isinstance(staged_file, _StagedWorkflowFile)
else staged_file
)
if isinstance(staged_file, _StagedWorkflowFile):
staged_file.verify_path()
if existed_before and dest_file.exists():
import tempfile
dest_state = dest_file.stat(follow_symlinks=False)
mode = dest_state.st_mode & 0o7777
if isinstance(staged_file, _StagedWorkflowFile):
staged_file.set_mode(mode)
else:
staged_path.chmod(mode)
fd, backup_name = tempfile.mkstemp(
dir=dest_file.parent,
prefix=f".{dest_file.name}.",
suffix=".bak",
)
try:
placeholder_state = os.fstat(fd)
finally:
os.close(fd)
backup_file = Path(backup_name)
try:
os.replace(dest_file, backup_file)
except BaseException as move_exc:
backup_state = None
try:
backup_state = backup_file.stat(follow_symlinks=False)
except OSError:
pass
if (
backup_state is not None
and os.path.samestat(dest_state, backup_state)
):
try:
os.replace(backup_file, dest_file)
except OSError as restore_exc:
raise OSError(
f"Failed to stage prior workflow ({move_exc}); failed "
f"to restore it from {backup_file} ({restore_exc}). "
f"The prior workflow remains at {backup_file}."
) from restore_exc
elif (
backup_state is not None
and os.path.samestat(placeholder_state, backup_state)
):
try:
backup_file.unlink(missing_ok=True)
except OSError:
pass
raise
try:
if isinstance(staged_file, _StagedWorkflowFile):
staged_file.verify_path()
# Windows cannot replace an open file. Verify through the
# exclusive descriptor, then close immediately before rename.
staged_file.close()
os.replace(staged_path, dest_file)
except BaseException as commit_exc:
try:
os.replace(backup_file, dest_file)
except OSError as restore_exc:
raise OSError(
f"Failed to commit workflow file ({commit_exc}); failed "
f"to restore the prior workflow from {backup_file} "
f"({restore_exc}). The prior workflow remains at "
f"{backup_file}."
) from restore_exc
raise
return backup_file
if isinstance(staged_file, _StagedWorkflowFile):
staged_file.verify_path()
staged_file.close()
os.replace(staged_path, dest_file)
return None
def _discard_staged_workflow_file(
staged_file: Path | _StagedWorkflowFile,
dest_dir: Path,
existed_before: bool,
) -> None:
"""Clean up after a pre-commit failure (staged_file was never swapped
onto dest_file): remove the staged file, and for a fresh install (no
prior directory) remove the now-orphaned dest_dir too. A genuine
removal failure must propagate (not be swallowed) so the safe wrapper
below can warn instead of silently leaving an orphan; a dest_dir
already absent is not itself an error."""
staged_path = (
staged_file.path
if isinstance(staged_file, _StagedWorkflowFile)
else staged_file
)
if isinstance(staged_file, _StagedWorkflowFile):
staged_file.close()
staged_path.unlink(missing_ok=True)
if not existed_before and dest_dir.exists():
import errno
try:
dest_dir.rmdir()
except OSError as exc:
# Another concurrent install may already have committed content
# into this once-fresh directory. Never recursively delete it.
if exc.errno not in (errno.ENOTEMPTY, errno.EEXIST):
raise
def _rollback_committed_workflow_file(
dest_file: Path, dest_dir: Path, existed_before: bool, backup_file: Path | None
) -> None:
"""Undo a successful _commit_workflow_file swap after a later failure
(registry.add()): restore the prior file via rename, remove the newly
committed file for a reinstall over a pre-existing empty directory
(no backup), or remove the new file and then its directory when empty
for a fresh install. A genuine removal failure must propagate (not be
swallowed) so the safe wrapper below can warn instead of silently
leaving an orphan; a dest_dir already absent is not itself an error."""
if backup_file is not None:
os.replace(backup_file, dest_file)
else:
dest_file.unlink(missing_ok=True)
if not existed_before and dest_dir.exists():
import errno
try:
dest_dir.rmdir()
except OSError as exc:
# Another installer may have staged a sibling before taking
# the transaction lock. Preserve it rather than recursively
# deleting the shared directory during this rollback.
if exc.errno not in (errno.ENOTEMPTY, errno.EEXIST):
raise
def _safe_discard_staged_workflow_file(
staged_file: Path | _StagedWorkflowFile,
dest_dir: Path,
existed_before: bool,
) -> None:
"""Guarded wrapper: a cleanup failure must be reported, never crash or
silently mask the original install error that triggered it."""
try:
_discard_staged_workflow_file(staged_file, dest_dir, existed_before)
except OSError as exc:
console.print(
"[yellow]Warning:[/yellow] Failed to clean up incomplete workflow "
f"install: {_escape_markup(str(exc))}"
)
def _safe_rollback_committed_workflow_file(
dest_file: Path, dest_dir: Path, existed_before: bool, backup_file: Path | None
) -> None:
"""Guarded wrapper: a rollback failure must be reported, never crash or
silently claim the prior workflow file was restored when it wasn't."""
try:
_rollback_committed_workflow_file(dest_file, dest_dir, existed_before, backup_file)
except OSError as exc:
console.print(
"[yellow]Warning:[/yellow] Failed to restore prior workflow file "
f"after registry update failure: {_escape_markup(str(exc))}"
)
def _discard_committed_backup_file(backup_file: Path | None) -> None:
"""Once registry.add()/registry.remove() has durably succeeded after a
_commit_workflow_file() swap, the renamed-aside prior file is no longer
needed for rollback -- it must be discarded, not left as a permanent
orphan sibling that every future reinstall would silently accumulate or
clobber. A cleanup failure here must not turn an already-successful
install into a reported failure; it's reported as a warning, consistent
with workflow_remove's post-commit cleanup semantics. A fresh install
(backup_file is None) is a no-op."""
if backup_file is None:
return
try:
backup_file.unlink(missing_ok=True)
except OSError as exc:
console.print(
"[yellow]Warning:[/yellow] Workflow installed, but its backup file "
f"could not be cleaned up: {_escape_markup(str(exc))}. Remove it "
f"manually: {_escape_markup(str(backup_file))}"
)
def _workflow_package_root(extracted_root: Path) -> Path:
"""Resolve a root-level or single-nested workflow package."""
if (extracted_root / "workflow.yml").is_file():
return extracted_root
entries = list(extracted_root.iterdir())
if (
len(entries) == 1
and entries[0].is_dir()
and not entries[0].is_symlink()
and (entries[0] / "workflow.yml").is_file()
):
return entries[0]
raise ValueError(
"Archive must contain workflow.yml at its root or in exactly one "
"top-level directory"
)
def _validate_local_workflow_package(package_dir: Path) -> None:
"""Reject links and special files before copying a local package."""
import stat
for root, dirnames, filenames in os.walk(package_dir, followlinks=False):
root_path = Path(root)
for name in [*dirnames, *filenames]:
path = root_path / name
mode = path.lstat().st_mode
if stat.S_ISLNK(mode):
raise ValueError(f"Workflow package contains symlink: {path}")
if not stat.S_ISDIR(mode) and not stat.S_ISREG(mode):
raise ValueError(f"Workflow package contains unsupported file: {path}")
def _workflow_versions_match(actual: object, expected: str) -> bool:
"""Compare workflow versions without treating equivalent spellings as changes."""
from packaging import version as pkg_version
try:
return pkg_version.Version(str(actual)) == pkg_version.Version(expected)
except pkg_version.InvalidVersion:
return str(actual) == expected
def _install_workflow_package(
project_root: Path,
workflows_dir: Path,
package_dir: Path,
source_label: str,
*,
expected_id: str | None = None,
expected_version: str | None = None,
expected_requires: dict[str, Any] | None = None,
exact_version: bool = False,
expected_installed_version: str | None = None,
catalog_info: dict[str, Any] | None = None,
) -> None:
"""Validate and atomically install a complete workflow package directory."""
import shutil
import tempfile
from .engine import WorkflowDefinition, validate_workflow
workflow_file = package_dir / "workflow.yml"
try:
_validate_local_workflow_package(package_dir)
workflow_bytes = workflow_file.read_bytes()
definition = WorkflowDefinition.from_string(workflow_bytes.decode("utf-8"))
except (OSError, UnicodeDecodeError, ValueError, yaml.YAMLError) as exc:
console.print(
f"[red]Error:[/red] Invalid workflow package: "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
errors = validate_workflow(definition)
if errors:
console.print("[red]Error:[/red] Workflow validation failed:")
for error in errors:
console.print(f" β’ {_escape_markup(str(error))}")
raise typer.Exit(1)
if not isinstance(definition.id, str) or not definition.id.strip():
console.print("[red]Error:[/red] Workflow definition has an empty or missing 'id'")
raise typer.Exit(1)
if expected_id is not None and definition.id != expected_id:
console.print(
f"[red]Error:[/red] Workflow ID in YAML "
f"({_escape_markup(repr(definition.id))}) does not match the requested "
f"workflow ID ({_escape_markup(repr(expected_id))})."
)
raise typer.Exit(1)
if expected_version is not None and not (
str(definition.version) == expected_version
if exact_version
else _workflow_versions_match(definition.version, expected_version)
):
console.print(
f"[red]Error:[/red] Downloaded workflow version "
f"({_escape_markup(str(definition.version))}) does not match the catalog "
f"version ({_escape_markup(expected_version)})."
)
raise typer.Exit(1)
if expected_requires is not None and definition.requires != expected_requires:
console.print(
"[red]Error:[/red] Downloaded workflow requirements do not match "
"the selected catalog release."
)
raise typer.Exit(1)
dest_dir = _safe_workflow_id_dir(workflows_dir, definition.id)
staged_dir = Path(
tempfile.mkdtemp(prefix=f".{definition.id}.installing-", dir=workflows_dir)
)
try:
package_root = package_dir.resolve()
def ignore_reserved_package_entries(
source: str, names: list[str]
) -> set[str]:
if Path(source).resolve() == package_root and "overlays" in names:
return {"overlays"}
return set()
shutil.copytree(
package_dir,
staged_dir,
dirs_exist_ok=True,
ignore=ignore_reserved_package_entries,
)
except OSError as exc:
shutil.rmtree(staged_dir, ignore_errors=True)
console.print(
f"[red]Error:[/red] Failed to stage workflow package: "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
backup_dir: Path | None = None
try:
with _workflow_install_transaction(project_root):
registry = _open_workflow_registry(project_root)
existing = registry.get(definition.id)
if expected_installed_version is not None and (
not isinstance(existing, dict)
or existing.get("source") != "catalog"
or not _workflow_versions_match(
existing.get("version"), expected_installed_version
)
):
console.print(
f"[yellow]Warning:[/yellow] Workflow "
f"'{_escape_markup(definition.id)}' changed during update; "
"rerun the command."
)
raise typer.Exit(1)
if dest_dir.exists():
backup_dir = Path(
tempfile.mkdtemp(
prefix=f".{definition.id}.backup-",
dir=workflows_dir,
)
)
backup_dir.rmdir()
os.replace(dest_dir, backup_dir)
try:
os.replace(staged_dir, dest_dir)
except BaseException:
if backup_dir is not None:
os.replace(backup_dir, dest_dir)
backup_dir = None
raise
entry = {
"name": definition.name,
"version": definition.version,
"description": definition.description,
"source": source_label,
}
if catalog_info is not None:
entry.update(
{
"source": "catalog",
"catalog_name": catalog_info.get("_catalog_name", ""),
"url": catalog_info.get("url", ""),
}
)
if isinstance(existing, dict) and not existing.get("enabled", True):
entry["enabled"] = False
try:
registry.add(definition.id, entry)
except (OSError, TypeError, ValueError):
failed_dir: Path | None = None
try:
failed_dir = Path(
tempfile.mkdtemp(
prefix=f".{definition.id}.failed-",
dir=workflows_dir,
)
)
failed_dir.rmdir()
os.replace(dest_dir, failed_dir)
if backup_dir is not None:
os.replace(backup_dir, dest_dir)
backup_dir = None
except OSError as rollback_exc:
console.print(
"[yellow]Warning:[/yellow] Failed to fully restore the prior "
f"workflow package: {_escape_markup(str(rollback_exc))}"
)
finally:
if failed_dir is not None and failed_dir.exists():
try:
shutil.rmtree(failed_dir)
except OSError as cleanup_exc:
console.print(
"[yellow]Warning:[/yellow] Could not remove failed "
f"workflow package: {_escape_markup(str(cleanup_exc))}"
)
raise
except typer.Exit:
raise
except (OSError, TypeError, ValueError) as exc:
console.print(
f"[red]Error:[/red] Failed to install workflow package: "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
finally:
if staged_dir.exists():
shutil.rmtree(staged_dir, ignore_errors=True)
if backup_dir is not None:
try:
shutil.rmtree(backup_dir)
except OSError as exc:
console.print(
"[yellow]Warning:[/yellow] Workflow installed, but its backup "
f"directory could not be removed: {_escape_markup(str(exc))}"
)
console.print(
f"[green]β[/green] Workflow '{_escape_markup(definition.name)}' "
f"({_escape_markup(definition.id)}) installed"
)
# Root helper re-fetched at call time so test monkeypatching of
# `specify_cli._require_specify_project` keeps working after the move.
def _require_specify_project(*args, **kwargs):
from .. import _require_specify_project as _f
project_root = _f(*args, **kwargs)
_reject_unsafe_workflow_storage(project_root)
return project_root
def _failed_step_error(state: Any) -> str | None:
"""Terminal error for a failed/aborted run, if any.
Returns the run-level error persisted by the engine at the moment
the run terminated. Returns ``None`` for non-terminal statuses so
the caller can print unconditionally.
"""
if getattr(state.status, "value", state.status) not in ("failed", "aborted"):
return None
return getattr(state, "error", None)
def _workflow_run_payload(state: Any) -> dict[str, Any]:
"""Machine-readable summary of a run/resume outcome."""
payload = {
"run_id": state.run_id,
"workflow_id": state.workflow_id,
"status": state.status.value,
"current_step_id": state.current_step_id,
"current_step_index": state.current_step_index,
}
gate = _gate_outcome(state)
if gate is not None:
payload["gate"] = gate
error = _failed_step_error(state)
if error is not None:
payload["error"] = error
if getattr(state, "execution", None):
from ._execution import scope_summaries
scopes = scope_summaries(state.execution, state.status.value)
if scopes:
payload["workflow_scopes"] = scopes
return payload
def _is_gate_step(step: dict[str, Any]) -> bool:
"""Whether a recorded step result is a gate.
Prefers the persisted ``type`` field, but when it is absent β a run paused
by an older version, whose step record predates ``type`` being stored β
falls back to the gate's unique output signature: only ``GateStep`` writes
an ``on_reject`` key. A record carrying a *different* known ``type`` is not
a gate, so the fallback applies only when ``type`` is missing entirely.
"""
step_type = step.get("type")
if step_type == "gate":
return True
if step_type:
return False
output = step.get("output")
return isinstance(output, dict) and "on_reject" in output
def _gate_outcome(state: Any) -> dict[str, Any] | None:
"""Gate detail for the structured outcome, when the run rests at a gate.
A paused or gate-aborted run is otherwise indistinguishable from any
other pause/abort in the machine-readable payload; surfacing the gate's
prompt, options, and (after an interactive choice) the decision lets
orchestrators drive review gates without parsing the human-facing stream.
"""
# Two run states rest *on* a gate: `paused` (awaiting a decision) and
# `aborted` (a gate rejected with `on_reject: abort` β the only path that
# sets ABORTED, leaving current_step_id on that gate). Any other status β
# notably `completed`/`failed` β must be suppressed: current_step_id is
# not cleared when a run whose last executed step was a gate moves on, so
# without this guard it would surface stale detail (run/resume/status).
if getattr(state.status, "value", state.status) not in ("paused", "aborted"):
return None
step = (getattr(state, "step_results", None) or {}).get(state.current_step_id)
step_id = state.current_step_id
scope_path = None
if getattr(state, "execution", None):
from ._execution import active_step
active = active_step(state.execution)
if active is None:
return None
path, node, step_id = active
scope_path = path[:-1]
step = node.get("result")
if not isinstance(step, dict) or not _is_gate_step(step):
return None
output = step.get("output") or {}
# `message`, `options`, and `choice` may be non-string YAML literals in
# legacy or synthetic records, so
# normalise all three for a stable JSON schema: message β str, options β
# list[str] | None, choice β str | None (None means no decision yet).
message = output.get("message")
choice = output.get("choice")
detail = {
"step_id": step_id,
"message": None if message is None else str(message),
"options": _normalize_gate_options(output.get("options")),
"choice": None if choice is None else str(choice),
}
if scope_path:
detail["scope_path"] = scope_path
return detail
def _normalize_gate_options(options: Any) -> list[str] | None:
"""Normalise a gate's ``options`` to a stable ``list[str]`` (or ``None``).
A valid gate stores a list, but an unvalidated workflow could leave a
scalar or tuple. ``None`` stays ``None`` (no options); a list/tuple maps
each element through ``str``; any other scalar becomes a single-element
list β so the emitted JSON schema is always ``list[str] | None``. A bare
string is treated as one option, never iterated character-by-character.
"""
if options is None:
return None
if isinstance(options, (list, tuple)):
return [str(o) for o in options]
return [str(options)]
def _run_outcome_exit_code(status_value: str) -> int:
"""Exit code for a finished run/resume: non-zero on terminal failure.
``failed`` and ``aborted`` map to 1 so scripts and orchestrators can
rely on the process exit code; ``completed`` and ``paused`` map to 0
(paused is a legitimate waiting state, not a failure).
"""
return 1 if status_value in ("failed", "aborted") else 0
def _emit_workflow_json(payload: dict[str, Any]) -> None:
"""Write a workflow payload as machine-readable JSON to stdout.
Uses the builtin ``print`` rather than ``console.print`` so Rich
markup interpretation, syntax highlighting, and line-wrapping can
never alter the emitted JSON.
"""
print(json.dumps(payload, indent=2))
@contextlib.contextmanager
def _stdout_to_stderr_when(active: bool):
"""Redirect everything written to stdout onto stderr while *active*.
Suppressing the banner and the step-start callback is not enough to
keep a ``--json`` stream clean: individual steps may still write to
stdout while the engine runs β the gate step prints its prompt,
and the prompt step runs a subprocess that inherits the process's
stdout file descriptor. Either would corrupt the single JSON object.
Redirecting at the file-descriptor level (``dup2``) captures both
Python-level writes and inherited-fd subprocess output, so step
progress lands on stderr (still visible to a human) while stdout
carries only the emitted JSON. A no-op when *active* is false.
"""
if not active:
yield
return
sys.stdout.flush()
saved_stdout_fd = os.dup(1)
try:
os.dup2(2, 1) # fd 1 (stdout) now points at fd 2 (stderr)
with contextlib.redirect_stdout(sys.stderr):
yield
finally:
sys.stdout.flush()
os.dup2(saved_stdout_fd, 1) # restore the real stdout
os.close(saved_stdout_fd)
def _install_workflow_from_catalog(
project_root: Path,
workflows_dir: Path,
workflow_id: str,
expected_version: str | None = None,
expected_installed_version: str | None = None,
requested_version: str | None = None,
selected_info: dict | None = None,
) -> None:
"""Download, validate, and register a catalog workflow.
Shared by ``workflow add`` and ``workflow update``. Raises ``typer.Exit``
on any failure; the registry entry is only written on full success.
``expected_version``, when given, rejects a downloaded workflow whose
version does not match the catalog version that triggered the install.
``expected_installed_version``, when given by ``workflow update``, aborts
if another process changes the installed source or version before commit.
``selected_info`` is a bundle-selected catalog record, used without a
second catalog lookup while retaining the same download and commit checks.
"""
from .catalog import WorkflowCatalog, WorkflowCatalogError
from .engine import WorkflowDefinition
safe_wf_id = _escape_markup(workflow_id)
if selected_info is not None:
info = selected_info
else:
catalog = WorkflowCatalog(project_root)
try:
info = (
catalog.get_workflow_info(workflow_id, requested_version)
if requested_version is not None
else catalog.get_workflow_info(workflow_id)
)
except WorkflowCatalogError as exc:
console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
raise typer.Exit(1)
if not info:
if requested_version is not None:
console.print(
f"[red]Error:[/red] Workflow '{safe_wf_id}' version "
f"'{_escape_markup(requested_version)}' not found in the winning catalog."
)
raise typer.Exit(1)
console.print(f"[red]Error:[/red] Workflow '{safe_wf_id}' not found in catalog")
raise typer.Exit(1)
if requested_version is not None:
expected_version = info["version"]
if not info.get("_install_allowed", True):
console.print(f"[yellow]Warning:[/yellow] Workflow '{safe_wf_id}' is from a discovery-only catalog")
console.print("Direct installation is not enabled for this catalog source.")
raise typer.Exit(1)
workflow_url = info.get("url")
if not workflow_url:
console.print(f"[red]Error:[/red] Workflow '{safe_wf_id}' does not have an install URL in the catalog")
raise typer.Exit(1)
if not isinstance(workflow_url, str):
# Untrusted catalog payload; a non-string would crash urlparse below.
console.print(
f"[red]Error:[/red] Workflow '{safe_wf_id}' has a malformed install URL."
)
raise typer.Exit(1)
# Validate URL scheme (HTTPS required, HTTP allowed for localhost only)
from urllib.parse import urlparse
try:
parsed_url = urlparse(workflow_url)
parsed_url.port
except ValueError:
console.print(
f"[red]Error:[/red] Workflow '{safe_wf_id}' has a malformed install URL."
)
raise typer.Exit(1)
if not is_https_or_localhost_http(workflow_url):
console.print(
f"[red]Error:[/red] Workflow '{safe_wf_id}' has an invalid install URL. "
"Only HTTPS URLs are allowed, except HTTP for localhost/loopback."
)
raise typer.Exit(1)
# Reject path traversal, symlinked <id>, and a symlinked workflow.yml leaf
# before any mkdir/download writes beneath the install directory.
workflow_dir = _safe_workflow_id_dir(workflows_dir, workflow_id)
workflow_file = workflow_dir / "workflow.yml"
# Captured before any mkdir/download writes so every failure branch below
# can tell a fresh install from a reinstall-over-an-existing-one,
# mirroring _validate_and_install_local's existed-before-aware cleanup.
existed_before = workflow_dir.is_dir()
try:
staged_file = _stage_workflow_file(
workflow_dir,
use_project_file_mode=not workflow_file.exists(),
)
except OSError as exc:
console.print(
f"[red]Error:[/red] Failed to install workflow '{safe_wf_id}' from catalog: "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
original_workflow_url = workflow_url
downloaded_archive_format = None
archive_content_type = None
try:
from specify_cli.authentication.http import open_url as _open_url
from specify_cli.authentication.http import github_provider_hosts as _github_provider_hosts
from specify_cli.authentication.github_http import (
resolve_github_release_asset_api_url as _resolve_gh_asset,
)
_wf_cat_extra_headers = None
_resolved_workflow_url = _resolve_gh_asset(
workflow_url,
_open_url,
timeout=30,
github_hosts=_github_provider_hosts(),
redirect_validator=_reject_insecure_download_redirect,
)
if _resolved_workflow_url:
workflow_url = _resolved_workflow_url
_wf_cat_extra_headers = {"Accept": "application/octet-stream"}
with _open_url(
workflow_url,
timeout=30,
extra_headers=_wf_cat_extra_headers,
redirect_validator=_reject_insecure_download_redirect,
) as response:
# Validate final URL after redirects
final_url = response.geturl()
if not is_https_or_localhost_http(final_url):
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(
f"[red]Error:[/red] Workflow '{safe_wf_id}' redirected to non-HTTPS URL: {_escape_markup(final_url)}"
)
raise typer.Exit(1)
archive_content_type = (
response.getheader("Content-Type")
if hasattr(response, "getheader")
else None
)
downloaded_archive_format = (
archive_format_from_name(final_url)
or archive_format_from_name(original_workflow_url)
or archive_format_from_content_type(archive_content_type)
)
# Written to the staging file, never workflow_file directly, so a
# reinstall's prior working copy is never touched until the
# atomic commit below runs.
if downloaded_archive_format is not None:
downloaded_content = read_response_limited(
response,
error_type=ValueError,
label=f"workflow '{workflow_id}' archive download",
)
elif _workflow_yaml_is_declared(final_url, archive_content_type):
downloaded_content = _read_response_within_limit(response)
else:
downloaded_content = read_response_limited(
response,
error_type=ValueError,
label=f"workflow '{workflow_id}' download",
)
downloaded_archive_format = _sniff_workflow_archive_format(
downloaded_content
)
if downloaded_archive_format is None:
_enforce_workflow_yaml_size(downloaded_content)
staged_file.write_bytes(downloaded_content)
except typer.Exit:
raise
except Exception as exc:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(f"[red]Error:[/red] Failed to install workflow '{safe_wf_id}' from catalog: {_escape_markup(str(exc))}")
raise typer.Exit(1)
try:
verify_archive_sha256(
downloaded_content, info.get("sha256"), workflow_id, ValueError
)
except ValueError as exc:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
raise typer.Exit(1)
if downloaded_archive_format is not None:
try:
import tempfile
from io import BytesIO
with tempfile.TemporaryDirectory(
prefix="speckit-workflow-archive-"
) as extract_dir:
extracted_root = Path(extract_dir)
safe_extract_archive(
staged_file.path,
extracted_root,
archive_file=BytesIO(downloaded_content),
source_name=original_workflow_url,
content_type=archive_content_type,
)
package_root = _workflow_package_root(extracted_root)
_safe_discard_staged_workflow_file(
staged_file,
workflow_dir,
existed_before,
)
_install_workflow_package(
project_root,
workflows_dir,
package_root,
workflow_url,
expected_id=workflow_id,
expected_version=expected_version,
expected_requires=(
info.get("requires") if requested_version is not None else None
),
exact_version=requested_version is not None,
expected_installed_version=expected_installed_version,
catalog_info={**info, "url": workflow_url},
)
except typer.Exit:
raise
except (OSError, ValueError) as exc:
_safe_discard_staged_workflow_file(
staged_file,
workflow_dir,
existed_before,
)
console.print(
f"[red]Error:[/red] Invalid workflow archive: "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
return
# Validate the downloaded workflow (still staged, not yet committed)
# before registering.
try:
definition = WorkflowDefinition.from_string(
downloaded_content.decode("utf-8")
)
except (UnicodeDecodeError, ValueError, yaml.YAMLError) as exc:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(f"[red]Error:[/red] Downloaded workflow is invalid: {_escape_markup(str(exc))}")
raise typer.Exit(1)
from .engine import validate_workflow
errors = validate_workflow(definition)
if errors:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print("[red]Error:[/red] Downloaded workflow validation failed:")
for err in errors:
console.print(f" \u2022 {_escape_markup(str(err))}")
raise typer.Exit(1)
# Enforce that the workflow's internal ID matches the catalog key
if definition.id and definition.id != workflow_id:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(
f"[red]Error:[/red] Workflow ID in YAML ({_escape_markup(repr(definition.id))}) "
f"does not match catalog key ({_escape_markup(repr(workflow_id))}). "
f"The catalog entry may be misconfigured."
)
raise typer.Exit(1)
# A stale or misconfigured URL can serve a different version than the
# catalog advertised; without this check `update` would report success
# while leaving the old version installed (or even downgrading).
if expected_version is not None and not (
str(definition.version) == expected_version
if requested_version is not None
else _workflow_versions_match(definition.version, expected_version)
):
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(
f"[red]Error:[/red] Downloaded workflow version ({_escape_markup(str(definition.version))}) "
f"does not match the catalog version ({_escape_markup(expected_version)}). "
f"The catalog entry may be stale or misconfigured."
)
raise typer.Exit(1)
if (
requested_version is not None
and "requires" in info
and definition.requires != info["requires"]
):
_safe_discard_staged_workflow_file(
staged_file, workflow_dir, existed_before
)
console.print(
"[red]Error:[/red] Downloaded workflow requirements do not match "
"the selected catalog release."
)
raise typer.Exit(1)
try:
transaction = _workflow_install_transaction(project_root)
with transaction:
transaction_existed_before = (
existed_before or workflow_file.exists()
)
transaction_registry = _open_workflow_registry(project_root)
if expected_installed_version is not None:
current = transaction_registry.get(workflow_id)
if (
not isinstance(current, dict)
or current.get("source") != "catalog"
or not _workflow_versions_match(
current.get("version"), expected_installed_version
)
):
console.print(
f"[yellow]Warning:[/yellow] Workflow '{safe_wf_id}' "
"changed during update; rerun the command to use its "
"current source and version."
)
raise typer.Exit(1)
# Commit the staged download onto workflow_file via an atomic
# swap. A prior file is renamed aside for registry rollback.
try:
backup_file = _commit_workflow_file(
staged_file, workflow_file, transaction_existed_before
)
except OSError as exc:
_safe_discard_staged_workflow_file(
staged_file, workflow_dir, existed_before
)
console.print(
f"[red]Error:[/red] Failed to install workflow "
f"'{safe_wf_id}' from catalog: {_escape_markup(str(exc))}"
)
raise typer.Exit(1)
entry = {
"name": definition.name or info.get("name", workflow_id),
"version": definition.version or info.get("version", "0.0.0"),
"description": definition.description
or info.get("description", ""),
"source": "catalog",
"catalog_name": info.get("_catalog_name", ""),
"url": workflow_url,
}
# Preserve a prior disabled state across updates/reinstalls.
existing = transaction_registry.get(workflow_id)
if isinstance(existing, dict) and not existing.get(
"enabled", True
):
entry["enabled"] = False
try:
transaction_registry.add(workflow_id, entry)
except (OSError, TypeError, ValueError) as exc:
_safe_rollback_committed_workflow_file(
workflow_file,
workflow_dir,
transaction_existed_before,
backup_file,
)
console.print(
f"[red]Error:[/red] Failed to update workflow registry for "
f"'{_escape_markup(workflow_id)}': "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
# Registry update succeeded while the transaction lock is held.
_discard_committed_backup_file(backup_file)
except typer.Exit:
_safe_discard_staged_workflow_file(
staged_file, workflow_dir, existed_before
)
raise
except OSError as exc:
_safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(
f"[red]Error:[/red] Failed to lock workflow install "
f"'{safe_wf_id}': "
f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
console.print(
f"[green]β[/green] Workflow '{_escape_markup(str(info.get('name', workflow_id)))}' "
"installed from catalog"
)
def _set_workflow_enabled(workflow_id: str, enabled: bool) -> None:
"""Update enabled state from a fresh registry snapshot while locked."""
project_root = _require_specify_project()
safe_id = _escape_markup(workflow_id)
try:
with _workflow_install_transaction(project_root):
registry = _open_workflow_registry(project_root)
metadata = registry.get(workflow_id)
if metadata is None:
console.print(
f"[red]Error:[/red] Workflow '{safe_id}' is not installed"
)
raise typer.Exit(1)
if not isinstance(metadata, dict):
console.print(
f"[red]Error:[/red] Registry entry for '{safe_id}' "
"is corrupted"
)
raise typer.Exit(1)
current = bool(metadata.get("enabled", True))
state = "enabled" if enabled else "disabled"
if current is enabled:
console.print(
f"[yellow]Workflow '{safe_id}' is already {state}[/yellow]"
)
raise typer.Exit(0)
try:
registry.add(workflow_id, {**metadata, "enabled": enabled})
except OSError as exc:
console.print(
f"[red]Error:[/red] Failed to update workflow registry "
f"for '{safe_id}': {_escape_markup(str(exc))}"
)
raise typer.Exit(1)
except OSError as exc:
console.print(
f"[red]Error:[/red] Failed to lock workflow registry for "
f"'{safe_id}': {_escape_markup(str(exc))}"
)
raise typer.Exit(1)
state = "enabled" if enabled else "disabled"
console.print(f"[green]β[/green] Workflow '{safe_id}' {state}")
# Compatibility forwarders for established public and direct-call paths.
def workflow_add(*args, **kwargs):
from .command_add import workflow_add as command
return command(*args, **kwargs)
def workflow_remove(*args, **kwargs):
from .command_remove import workflow_remove as command
return command(*args, **kwargs)
def workflow_status(*args, **kwargs):
from .command_status import workflow_status as command
return command(*args, **kwargs)
def workflow_enable(*args, **kwargs):
from .command_enable import workflow_enable as command
return command(*args, **kwargs)
def workflow_disable(*args, **kwargs):
from .command_disable import workflow_disable as command
return command(*args, **kwargs)
def workflow_step_add(*args, **kwargs):
from .step.command_add import workflow_step_add as command
return command(*args, **kwargs)
def workflow_step_remove(*args, **kwargs):
from .step.command_remove import workflow_step_remove as command
return command(*args, **kwargs)
def register(app: typer.Typer) -> None:
"""Attach the workflow command group to the root Typer app."""
from .catalog import register as register_catalog
from .overlay import register as register_overlay
from .step import register as register_step
register_catalog(workflow_app)
register_step(workflow_app)
register_overlay(workflow_app)
# isort: off
from . import command_run # noqa: F401 -- registers handler
from . import command_resume # noqa: F401 -- registers handler
from . import command_status # noqa: F401 -- registers handler
from . import command_list # noqa: F401 -- registers handler
from . import command_add # noqa: F401 -- registers handler
from . import command_remove # noqa: F401 -- registers handler
from . import command_update # noqa: F401 -- registers handler
from . import command_enable # noqa: F401 -- registers handler
from . import command_disable # noqa: F401 -- registers handler
from . import command_search # noqa: F401 -- registers handler
from . import command_info # noqa: F401 -- registers handler
from . import command_resolve # noqa: F401 -- registers handler
# isort: on
app.add_typer(workflow_app, name="workflow")