Skip to content

💫 Toolkit to help you get started with SDD or any other process!

refactor: organize workflow CLI commands (#4673)

Manfred Riemc31168a7a58d
diff --git a/design/cli.md b/design/cli.md
index ff1ae2678..9ee3c91a9 100644
--- a/design/cli.md
+++ b/design/cli.md
@@ -148,11 +148,20 @@ extensions/
The nested package's `__init__.py` owns its Typer application and registration.
Shared helpers for that nested surface can live in `_helpers.py`.
-Creating a nested CLI package does not transfer same-named domain behavior into
-that package. If an existing domain module collides with a new nested command
-namespace, keep the implementation in the parent domain package (or a focused
-domain module there). Preserve an established import path through thin
-compatibility exports from the nested package when required.
+A nested CLI hierarchy may also be the root of a bounded subdomain when its
+concept depends on the parent domain but owns a distinct resource and lifecycle
+that the parent commands do not cover. In that case, keep the subdomain's
+non-command modules and its `command_*.py` adapters together in the nested
+package. Storage, validation, composition, or distribution behavior specific to
+that resource are signals that the namespace is a domain root, not merely a CLI
+group.
+
+Creating a nested CLI package solely to group commands does not transfer
+same-named parent-domain behavior into that package. If an existing domain
+module merely collides with a new nested command namespace, keep the
+implementation in the parent domain package (or a focused domain module there).
+Preserve an established import path through thin compatibility exports from the
+nested package when required.
Do not add a nested `_commands.py` merely for symmetry. Create one only when
the nested group develops substantial shared command infrastructure that no
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index eee6dce00..cfcc51e35 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -592,12 +592,11 @@ _register_workflow_cmds(app)
# Re-exported at the package root because bundler primitives import these
# handlers via ``from specify_cli import workflow_*`` (and tests monkeypatch
# ``specify_cli.workflow_add``). Keep these names resolvable from the root.
-from .workflows._commands import ( # noqa: E402,F401
- workflow_add,
- workflow_remove,
- workflow_step_add,
- workflow_step_remove,
-)
+from .workflows.command_add import workflow_add # noqa: E402,F401
+from .workflows.command_remove import workflow_remove # noqa: E402,F401
+from .workflows.step.command_add import workflow_step_add # noqa: E402,F401
+from .workflows.step.command_remove import workflow_step_remove # noqa: E402,F401
+
def main():
# On Windows the default stdout/stderr code page (e.g. cp1252) cannot encode
diff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.py
index 1e608ca16..2bb3de56a 100644
--- a/src/specify_cli/workflows/__init__.py
+++ b/src/specify_cli/workflows/__init__.py
@@ -44,18 +44,18 @@ def get_step_type(type_key: str) -> StepBase | None:
def _register_builtin_steps() -> None:
"""Register all built-in step types."""
- from .steps.command import CommandStep
- from .steps.do_while import DoWhileStep
- from .steps.fan_in import FanInStep
- from .steps.fan_out import FanOutStep
- from .steps.gate import GateStep
- from .steps.if_then import IfThenStep
- from .steps.init import InitStep
- from .steps.prompt import PromptStep
- from .steps.shell import ShellStep
- from .steps.slot import SlotStep
- from .steps.switch import SwitchStep
- from .steps.while_loop import WhileStep
+ from .step.command import CommandStep
+ from .step.do_while import DoWhileStep
+ from .step.fan_in import FanInStep
+ from .step.fan_out import FanOutStep
+ from .step.gate import GateStep
+ from .step.if_then import IfThenStep
+ from .step.init import InitStep
+ from .step.prompt import PromptStep
+ from .step.shell import ShellStep
+ from .step.slot import SlotStep
+ from .step.switch import SwitchStep
+ from .step.while_loop import WhileStep
_register_step(CommandStep())
_register_step(DoWhileStep())
diff --git a/src/specify_cli/workflows/_command_resume_state.py b/src/specify_cli/workflows/_command_resume_state.py
new file mode 100644
index 000000000..935bb17e9
--- /dev/null
+++ b/src/specify_cli/workflows/_command_resume_state.py
@@ -0,0 +1,49 @@
+"""Resume-private installed-workflow owner state resolution."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _path_has_symlink_component(path: Path) -> bool:
+ """Return whether any component of an absolute path is a symlink."""
+ absolute = Path(os.path.abspath(path))
+ current = Path(absolute.anchor)
+ for part in absolute.parts[1:]:
+ current /= part
+ if current.is_symlink():
+ return True
+ return False
+
+
+def _resolve_run_owner_root(
+ installed_registry_root: str | None, project_root: Path
+) -> Path:
+ """Determine which project's registry gates resuming a run.
+
+ ``installed_registry_root`` is only ever persisted when the run's
+ 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) -- see ``workflow_run``. The common
+ case (an installed workflow run from its own project) stores ``None``,
+ so a later project rename/move is transparently picked up here by
+ falling back to the *current* ``project_root`` instead of a stale
+ absolute path baked in at run start.
+
+ A persisted cross-project root that no longer exists cannot be safely
+ rediscovered and must fail closed instead of consulting the unrelated
+ project that happens to store the run state.
+ """
+ if installed_registry_root:
+ candidate = Path(installed_registry_root)
+ if (
+ candidate.is_absolute()
+ and not _path_has_symlink_component(candidate)
+ and candidate.is_dir()
+ ):
+ return candidate
+ raise ValueError(
+ "Installed workflow owner is unavailable; cannot safely resume"
+ )
+ return project_root
diff --git a/src/specify_cli/workflows/_command_run_ownership.py b/src/specify_cli/workflows/_command_run_ownership.py
new file mode 100644
index 000000000..322a05f2b
--- /dev/null
+++ b/src/specify_cli/workflows/_command_run_ownership.py
@@ -0,0 +1,187 @@
+"""Run-private installed-workflow ownership resolution."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from . import _commands as cli
+
+
+def _same_existing_path(left: Path, right: Path) -> bool:
+ """Return whether two existing paths identify the same filesystem entry."""
+ try:
+ return os.path.samefile(left, right)
+ except OSError:
+ return left == right
+
+
+def _scan_for_workflow_owner(parts: tuple[str, ...]) -> int | None:
+ """Find the *nearest* (innermost) ``.specify/workflows/<id>`` owner in
+ *parts*, scanning from the end of the path.
+
+ Scanning from the end (rather than stopping at the first match from the
+ start) matters for a project nested beneath an unrelated outer path that
+ happens to reuse the same ``.specify``/``workflows`` segment names: the
+ first-from-start match would pick the outer directory and the wrong
+ workflow ID, silently missing the real (inner) owner's disabled check.
+
+ Returns the index of the owning ``.specify`` segment, or ``None`` if no
+ owner segment is present.
+ """
+ for i in range(len(parts) - 3, -1, -1):
+ if (
+ parts[i].casefold() == ".specify"
+ and parts[i + 1].casefold() == "workflows"
+ ):
+ return i
+ return None
+
+
+def _expand_first_symlink_target(path: Path) -> Path | None:
+ """Expand one symlink component while preserving the remaining path."""
+ parts = path.parts
+ current = Path(path.anchor) if path.is_absolute() else Path()
+ start = 1 if path.is_absolute() else 0
+ for index in range(start, len(parts)):
+ current = current / parts[index]
+ if not current.is_symlink():
+ continue
+ try:
+ target = Path(os.readlink(current))
+ except OSError:
+ return None
+ if not target.is_absolute():
+ target = current.parent / target
+ expanded = target.joinpath(*parts[index + 1 :])
+ return Path(os.path.normpath(str(expanded.absolute())))
+ return None
+
+
+def _resolve_installed_workflow_ownership(
+ source_path: Path, err
+) -> tuple[Path | None, str | None]:
+ """Map a direct ``workflow.yml`` *source_path* back to the installed
+ workflow (``registry_root``, ``registered_id``) it belongs to, if any.
+
+ A registered path can point at installed storage three ways, all of
+ which must receive the same registry disabled-check:
+
+ 1. Lexically: the path's own (symlink-preserving) segments identify
+ ``.specify/workflows/<id>`` -- collapsing ``..``/``.`` but
+ never resolving symlinks, so a symlinked ``workflow.yml`` leaf (or
+ symlinked ``<id>`` directory) inside the owned tree is caught by the
+ inward-symlink refusal below rather than silently followed.
+ 2. Via an intermediate alias target whose lexical path identifies
+ ``.specify/workflows/<id>`` before a symlinked storage ancestor is
+ resolved away.
+ 3. Via an outward-pointing alias whose fully resolved target lands
+ inside legitimate installed storage, even though the raw invocation
+ path has no ownership segments.
+
+ Returns ``(None, None)`` when neither applies -- a genuinely standalone
+ external workflow file, which is allowed to run unchecked.
+ """
+ def ownership_for(candidate: Path) -> tuple[Path, str] | None:
+ parts = candidate.parts
+ i = _scan_for_workflow_owner(parts)
+ if i is None:
+ return None
+ registry_root = (
+ Path(*parts[:i]) if i else Path(candidate.anchor or ".")
+ )
+ candidate_specify = Path(*parts[: i + 1])
+ candidate_workflows = Path(*parts[: i + 2])
+ candidate_id_dir = Path(*parts[: i + 3])
+ canonical_specify = registry_root / ".specify"
+ canonical_workflows = canonical_specify / "workflows"
+ # The path-derived registry_root here may differ from the cwd's
+ # project_root already checked by _reject_unsafe_workflow_storage
+ # (e.g. this path points into another project entirely, or this
+ # project's own .specify is itself a symlink to an
+ # attacker-controlled tree) -- check it explicitly rather than
+ # trusting that cwd-scoped guard, and don't rely on
+ # WorkflowRegistry's own symlinked-parent handling as the safety
+ # signal here: it fails closed by raising OSError at construction
+ # time (see catalog.py's _load), but that surfaces as an opaque
+ # exception rather than this guard's clean, specific CLI error for
+ # the actual owning project root.
+ cli._reject_unsafe_dir(canonical_specify, ".specify")
+ cli._reject_unsafe_dir(canonical_workflows, ".specify/workflows")
+ cli._reject_unsafe_dir(candidate_specify, ".specify")
+ cli._reject_unsafe_dir(candidate_workflows, ".specify/workflows")
+ try:
+ if not os.path.samefile(candidate_specify, canonical_specify):
+ return None
+ if not os.path.samefile(
+ candidate_workflows, canonical_workflows
+ ):
+ return None
+ except OSError:
+ return None
+ registry = cli._open_workflow_registry(registry_root, err)
+ registered_id = None
+ for workflow_id in registry.list():
+ if (
+ not isinstance(workflow_id, str)
+ or workflow_id in cli._RESERVED_WORKFLOW_IDS
+ or not cli._WORKFLOW_ID_PATTERN.fullmatch(workflow_id)
+ ):
+ continue
+ try:
+ if os.path.samefile(
+ candidate_id_dir,
+ canonical_workflows / workflow_id,
+ ):
+ registered_id = workflow_id
+ break
+ except OSError:
+ continue
+ if registered_id is None:
+ return None
+ # A legitimately installed workflow's own directory tree never
+ # contains a symlink (workflow add/remove both refuse one at
+ # install time); one appearing here means the file actually loaded
+ # below would not be the file this ownership match is based on, so
+ # refuse rather than silently mismatch.
+ for k in range(i + 2, len(parts) + 1):
+ if Path(*parts[:k]).is_symlink():
+ err.print(
+ "[red]Error:[/red] Refusing to run: "
+ f".specify/workflows/{cli._escape_markup(registered_id)} "
+ "contains a symlinked path component"
+ )
+ raise cli.typer.Exit(1)
+ return registry_root, registered_id
+
+ lexical = Path(os.path.normpath(str(source_path.absolute())))
+ ownership = ownership_for(lexical)
+ if ownership is not None:
+ return ownership
+
+ # Inspect each intermediate symlink target before fully resolving it.
+ # Full resolution can erase .specify/workflows ownership segments when
+ # one of those storage directories is itself a symlink.
+ candidate = lexical
+ seen = {candidate}
+ for _ in range(40):
+ expanded = _expand_first_symlink_target(candidate)
+ if expanded is None or expanded in seen:
+ break
+ ownership = ownership_for(expanded)
+ if ownership is not None:
+ return ownership
+ seen.add(expanded)
+ candidate = expanded
+
+ # A fully resolved target may still land in legitimate installed
+ # storage through an unrelated-looking alias.
+ try:
+ resolved = source_path.resolve(strict=False)
+ except (OSError, RuntimeError):
+ return None, None
+ if resolved == lexical:
+ # Nothing on this path is a symlink; already covered above.
+ return None, None
+ ownership = ownership_for(resolved)
+ return ownership if ownership is not None else (None, None)
diff --git a/src/specify_cli/workflows/_commands.py b/src/specify_cli/workflows/_commands.py
index 769106671..940fa6163 100644
--- a/src/specify_cli/workflows/_commands.py
+++ b/src/specify_cli/workflows/_commands.py
@@ -1,9 +1,7 @@
-"""specify workflow * command handlers — app objects and register().
+"""Shared infrastructure and registration for ``specify workflow`` commands.
-Moved out of __init__.py (PR-8/8). Handlers reference `_require_specify_project`
-(kept in the package root) through the thin shim below, which re-fetches from
-the parent package at call time so test monkeypatching of
-`specify_cli._require_specify_project` keeps working.
+Decorated handlers live in command modules matching the CLI surface. Thin
+forwarders preserve established direct-import and monkeypatch boundaries.
"""
from __future__ import annotations
@@ -12,7 +10,7 @@ import json
import os
import re
import sys
-from pathlib import Path, PurePosixPath
+from pathlib import Path, PurePosixPath as PurePosixPath
from typing import Any
import typer
@@ -23,14 +21,14 @@ from .._console import console, err_console
from .._download_security import (
archive_format_from_content_type,
archive_format_from_name,
- archive_suffix,
+ 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
+from .._project import _resolve_init_dir_override as _resolve_init_dir_override
from ..shared_infra import verify_archive_sha256
workflow_app = typer.Typer(
@@ -39,34 +37,6 @@ workflow_app = typer.Typer(
add_completion=False,
)
-workflow_catalog_app = typer.Typer(
- name="catalog",
- help="Manage workflow catalogs",
- add_completion=False,
-)
-workflow_app.add_typer(workflow_catalog_app, name="catalog")
-
-workflow_step_app = typer.Typer(
- name="step",
- help="Manage workflow step types",
- add_completion=False,
-)
-workflow_app.add_typer(workflow_step_app, name="step")
-
-workflow_step_catalog_app = typer.Typer(
- name="catalog",
- help="Manage step catalogs",
- add_completion=False,
-)
-workflow_step_app.add_typer(workflow_step_catalog_app, name="catalog")
-
-workflow_overlay_app = typer.Typer(
- name="overlay",
- help="Manage workflow overlays",
- add_completion=False,
-)
-workflow_app.add_typer(workflow_overlay_app, name="overlay")
-
def _error_console(json_output: bool):
"""Console for error text: stderr under ``--json`` so the JSON stdout
@@ -115,55 +85,13 @@ def _require_enabled_workflow(
return metadata is not None
-def _path_has_symlink_component(path: Path) -> bool:
- """Return whether any component of an absolute path is a symlink."""
- absolute = Path(os.path.abspath(path))
- current = Path(absolute.anchor)
- for part in absolute.parts[1:]:
- current /= part
- if current.is_symlink():
- return True
- return False
-
-
-def _same_existing_path(left: Path, right: Path) -> bool:
- """Return whether two existing paths identify the same filesystem entry."""
- try:
- return os.path.samefile(left, right)
- except OSError:
- return left == right
-
-
def _resolve_run_owner_root(
installed_registry_root: str | None, project_root: Path
) -> Path:
- """Determine which project's registry gates resuming a run.
-
- ``installed_registry_root`` is only ever persisted when the run's
- 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) -- see ``workflow_run``. The common
- case (an installed workflow run from its own project) stores ``None``,
- so a later project rename/move is transparently picked up here by
- falling back to the *current* ``project_root`` instead of a stale
- absolute path baked in at run start.
-
- A persisted cross-project root that no longer exists cannot be safely
- rediscovered and must fail closed instead of consulting the unrelated
- project that happens to store the run state.
- """
- if installed_registry_root:
- candidate = Path(installed_registry_root)
- if (
- candidate.is_absolute()
- and not _path_has_symlink_component(candidate)
- and candidate.is_dir()
- ):
- return candidate
- raise ValueError(
- "Installed workflow owner is unavailable; cannot safely resume"
- )
- return project_root
+ """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(
@@ -216,175 +144,14 @@ def _reject_unsafe_workflow_storage(project_root: Path) -> None:
)
-def _scan_for_workflow_owner(parts: tuple[str, ...]) -> int | None:
- """Find the *nearest* (innermost) ``.specify/workflows/<id>`` owner in
- *parts*, scanning from the end of the path.
-
- Scanning from the end (rather than stopping at the first match from the
- start) matters for a project nested beneath an unrelated outer path that
- happens to reuse the same ``.specify``/``workflows`` segment names: the
- first-from-start match would pick the outer directory and the wrong
- workflow ID, silently missing the real (inner) owner's disabled check.
-
- Returns the index of the owning ``.specify`` segment, or ``None`` if no
- owner segment is present.
- """
- for i in range(len(parts) - 3, -1, -1):
- if (
- parts[i].casefold() == ".specify"
- and parts[i + 1].casefold() == "workflows"
- ):
- return i
- return None
-
-
-def _expand_first_symlink_target(path: Path) -> Path | None:
- """Expand one symlink component while preserving the remaining path."""
- parts = path.parts
- current = Path(path.anchor) if path.is_absolute() else Path()
- start = 1 if path.is_absolute() else 0
- for index in range(start, len(parts)):
- current = current / parts[index]
- if not current.is_symlink():
- continue
- try:
- target = Path(os.readlink(current))
- except OSError:
- return None
- if not target.is_absolute():
- target = current.parent / target
- expanded = target.joinpath(*parts[index + 1 :])
- return Path(os.path.normpath(str(expanded.absolute())))
- return None
-
-
def _resolve_installed_workflow_ownership(
source_path: Path, err
) -> tuple[Path | None, str | None]:
- """Map a direct ``workflow.yml`` *source_path* back to the installed
- workflow (``registry_root``, ``registered_id``) it belongs to, if any.
-
- A registered path can point at installed storage three ways, all of
- which must receive the same registry disabled-check:
-
- 1. Lexically: the path's own (symlink-preserving) segments identify
- ``.specify/workflows/<id>`` -- collapsing ``..``/``.`` but
- never resolving symlinks, so a symlinked ``workflow.yml`` leaf (or
- symlinked ``<id>`` directory) inside the owned tree is caught by the
- inward-symlink refusal below rather than silently followed.
- 2. Via an intermediate alias target whose lexical path identifies
- ``.specify/workflows/<id>`` before a symlinked storage ancestor is
- resolved away.
- 3. Via an outward-pointing alias whose fully resolved target lands
- inside legitimate installed storage, even though the raw invocation
- path has no ownership segments.
-
- Returns ``(None, None)`` when neither applies -- a genuinely standalone
- external workflow file, which is allowed to run unchecked.
- """
- def ownership_for(candidate: Path) -> tuple[Path, str] | None:
- parts = candidate.parts
- i = _scan_for_workflow_owner(parts)
- if i is None:
- return None
- registry_root = (
- Path(*parts[:i]) if i else Path(candidate.anchor or ".")
- )
- candidate_specify = Path(*parts[: i + 1])
- candidate_workflows = Path(*parts[: i + 2])
- candidate_id_dir = Path(*parts[: i + 3])
- canonical_specify = registry_root / ".specify"
- canonical_workflows = canonical_specify / "workflows"
- # The path-derived registry_root here may differ from the cwd's
- # project_root already checked by _reject_unsafe_workflow_storage
- # (e.g. this path points into another project entirely, or this
- # project's own .specify is itself a symlink to an
- # attacker-controlled tree) -- check it explicitly rather than
- # trusting that cwd-scoped guard, and don't rely on
- # WorkflowRegistry's own symlinked-parent handling as the safety
- # signal here: it fails closed by raising OSError at construction
- # time (see catalog.py's _load), but that surfaces as an opaque
- # exception rather than this guard's clean, specific CLI error for
- # the actual owning project root.
- _reject_unsafe_dir(canonical_specify, ".specify")
- _reject_unsafe_dir(canonical_workflows, ".specify/workflows")
- _reject_unsafe_dir(candidate_specify, ".specify")
- _reject_unsafe_dir(candidate_workflows, ".specify/workflows")
- try:
- if not os.path.samefile(candidate_specify, canonical_specify):
- return None
- if not os.path.samefile(
- candidate_workflows, canonical_workflows
- ):
- return None
- except OSError:
- return None
- registry = _open_workflow_registry(registry_root, err)
- registered_id = None
- for workflow_id in registry.list():
- if (
- not isinstance(workflow_id, str)
- or workflow_id in _RESERVED_WORKFLOW_IDS
- or not _WORKFLOW_ID_PATTERN.fullmatch(workflow_id)
- ):
- continue
- try:
- if os.path.samefile(
- candidate_id_dir,
- canonical_workflows / workflow_id,
- ):
- registered_id = workflow_id
- break
- except OSError:
- continue
- if registered_id is None:
- return None
- # A legitimately installed workflow's own directory tree never
- # contains a symlink (workflow add/remove both refuse one at
- # install time); one appearing here means the file actually loaded
- # below would not be the file this ownership match is based on, so
- # refuse rather than silently mismatch.
- for k in range(i + 2, len(parts) + 1):
- if Path(*parts[:k]).is_symlink():
- err.print(
- "[red]Error:[/red] Refusing to run: "
- f".specify/workflows/{_escape_markup(registered_id)} "
- "contains a symlinked path component"
- )
- raise typer.Exit(1)
- return registry_root, registered_id
-
- lexical = Path(os.path.normpath(str(source_path.absolute())))
- ownership = ownership_for(lexical)
- if ownership is not None:
- return ownership
-
- # Inspect each intermediate symlink target before fully resolving it.
- # Full resolution can erase .specify/workflows ownership segments when
- # one of those storage directories is itself a symlink.
- candidate = lexical
- seen = {candidate}
- for _ in range(40):
- expanded = _expand_first_symlink_target(candidate)
- if expanded is None or expanded in seen:
- break
- ownership = ownership_for(expanded)
- if ownership is not None:
- return ownership
- seen.add(expanded)
- candidate = expanded
-
- # A fully resolved target may still land in legitimate installed
- # storage through an unrelated-looking alias.
- try:
- resolved = source_path.resolve(strict=False)
- except (OSError, RuntimeError):
- return None, None
- if resolved == lexical:
- # Nothing on this path is a symlink; already covered above.
- return None, None
- ownership = ownership_for(resolved)
- return ownership if ownership is not None else (None, 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])?$")
@@ -408,12 +175,6 @@ def _reject_insecure_download_redirect(old_url: str, new_url: str) -> None:
# a ceiling any legitimate workflow definition should ever approach.
_MAX_WORKFLOW_YAML_BYTES = 5 * 1024 * 1024 # 5 MiB
_DOWNLOAD_CHUNK_SIZE = 65536
-# Custom step packages contain executable Python, metadata, and optional helper
-# files downloaded one-by-one rather than as an archive. Mirror the archive
-# ceilings so a catalog cannot turn individually valid files into an unbounded
-# aggregate download.
-_MAX_STEP_PACKAGE_FILES = 512
-_MAX_STEP_PACKAGE_BYTES = 50 * 1024 * 1024 # 50 MiB
def _read_response_within_limit(response, max_bytes: int | None = None) -> bytes:
@@ -955,11 +716,6 @@ def _validate_local_workflow_package(package_dir: Path) -> None:
raise ValueError(f"Workflow package contains unsupported file: {path}")
-def _workflow_package_has_companions(package_dir: Path) -> bool:
- """Return whether a directory contains anything beyond workflow.yml."""
- return any(path.name != "workflow.yml" for path in package_dir.iterdir())
-
-
def _install_workflow_package(
project_root: Path,
workflows_dir: Path,
@@ -1305,2597 +1061,473 @@ def _stdout_to_stderr_when(active: bool):
os.close(saved_stdout_fd)
-@workflow_app.command("run")
-def workflow_run(
- source: str = typer.Argument(..., help="Workflow ID or YAML file path"),
- input_values: list[str] | None = typer.Option(
- None, "--input", "-i", help="Input values as key=value pairs"
- ),
- json_output: bool = 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 . import load_custom_steps
- from .engine import WorkflowEngine
-
- source_path = 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 = _resolve_init_dir_override()
- project_root = override if override is not None else Path.cwd()
- _reject_unsafe_workflow_storage(project_root)
- else:
- project_root = _require_specify_project()
-
- load_custom_steps(project_root)
- engine = WorkflowEngine(project_root)
- 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: console.print(
- f" \u25b8 \\[{_escape_markup(str(sid))}] "
- f"{_escape_markup(str(label))} \u2026"
- )
-
- err = _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 _RESERVED_WORKFLOW_IDS or not _WORKFLOW_ID_PATTERN.fullmatch(source):
- err.print(
- f"[red]Error:[/red] Invalid workflow ID: {_escape_markup(repr(source))}"
- )
- raise 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 = _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:
- _require_enabled_workflow(registry_root, registered_id, err)
+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,
+) -> None:
+ """Download, validate, and register a catalog workflow.
- 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 typer.Exit(1)
- except ValueError as exc:
- err.print(f"[red]Error:[/red] Invalid workflow: {_escape_markup(str(exc))}")
- raise typer.Exit(1)
+ 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.
+ """
+ from .catalog import WorkflowCatalog, WorkflowCatalogError
+ from .engine import WorkflowDefinition
- # Validate
- errors = engine.validate(definition)
- if errors:
- err.print("[red]Workflow validation failed:[/red]")
- for verr in errors:
- err.print(f" • {_escape_markup(str(verr))}")
- raise typer.Exit(1)
+ def versions_match(actual: object, expected: str) -> bool:
+ from packaging import version as pkg_version
- # Parse inputs
- inputs = _parse_input_values(input_values, json_output=json_output)
+ try:
+ return pkg_version.Version(str(actual)) == pkg_version.Version(
+ expected
+ )
+ except pkg_version.InvalidVersion:
+ return str(actual) == expected
- if not json_output:
- console.print(f"\n[bold cyan]Running workflow:[/bold cyan] {definition.name} ({definition.id})")
- console.print(f"[dim]Version: {definition.version}[/dim]\n")
+ safe_wf_id = _escape_markup(workflow_id)
+ catalog = WorkflowCatalog(project_root)
try:
- with _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 _same_existing_path(registry_root, project_root)
- else None
- ),
- )
- except ValueError as exc:
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- except Exception as exc:
- err.print(f"[red]Workflow failed:[/red] {_escape_markup(str(exc))}")
+ info = 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 json_output:
- _emit_workflow_json(_workflow_run_payload(state))
- raise typer.Exit(_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")
- console.print(f"\n[{color}]Status: {state.status.value}[/{color}]")
- console.print(f"[dim]Run ID: {state.run_id}[/dim]")
-
- err_msg = _failed_step_error(state)
- if err_msg:
- console.print(f"[red]Error:[/red] {_escape_markup(err_msg)}")
-
- if state.status.value == "paused":
- console.print(f"\nResume with: [cyan]specify workflow resume {state.run_id}[/cyan]")
-
- raise typer.Exit(_run_outcome_exit_code(state.status.value))
-
-
-@workflow_app.command("resume")
-def workflow_resume(
- run_id: str = typer.Argument(..., help="Run ID to resume"),
- input_values: list[str] | None = typer.Option(
- None, "--input", "-i", help="Updated input values as key=value pairs"
- ),
- json_output: bool = typer.Option(
- False,
- "--json",
- help="Emit the resume outcome as a single JSON object instead of formatted text.",
- ),
-):
- """Resume a paused or failed workflow run."""
- from . import load_custom_steps
- from .engine import RunState, WorkflowEngine
-
- project_root = _require_specify_project()
- load_custom_steps(project_root)
- engine = WorkflowEngine(project_root)
- 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: console.print(
- f" \u25b8 \\[{_escape_markup(str(sid))}] "
- f"{_escape_markup(str(label))} \u2026"
- )
-
- inputs = _parse_input_values(input_values, json_output=json_output)
- err = _error_console(json_output)
+ if not info:
+ console.print(f"[red]Error:[/red] Workflow '{safe_wf_id}' not found in catalog")
+ raise typer.Exit(1)
- # Pre-load the persisted run state so a run started from an installed
- # workflow that has since been disabled cannot resume unchecked --
- # engine.resume() replays the run directly from disk with no registry
- # awareness at all, which would otherwise bypass the same disabled
- # guard `workflow run` enforces. Runs without installed_workflow_id
- # (a direct/non-installed source, or a run persisted before this field
- # existed) are unaffected and resume exactly as before.
- try:
- pre_state = RunState.load(run_id, project_root)
- except FileNotFoundError:
- err.print(f"[red]Error:[/red] Run not found: {run_id}")
+ 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)
- except ValueError as exc:
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
+
+ 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)
- except OSError as exc:
- err.print(f"[red]Resume failed:[/red] {_escape_markup(str(exc))}")
+ 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)
- if pre_state.installed_workflow_id is not None:
- try:
- owner_root = _resolve_run_owner_root(
- pre_state.installed_registry_root, project_root
- )
- except ValueError as exc:
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- _require_enabled_workflow(
- owner_root, pre_state.installed_workflow_id, err
- )
- elif not pre_state.installed_origin_tracked:
- if _require_enabled_workflow(
- project_root, pre_state.workflow_id, err
- ):
- pre_state.installed_workflow_id = pre_state.workflow_id
- pre_state.installed_origin_tracked = True
- try:
- pre_state.save()
- except OSError as exc:
- err.print(f"[red]Resume failed:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
+ # Validate URL scheme (HTTPS required, HTTP allowed for localhost only)
+ from urllib.parse import urlparse
try:
- with _stdout_to_stderr_when(json_output):
- state = engine.resume(run_id, inputs or None)
- except FileNotFoundError:
- err.print(f"[red]Error:[/red] Run not found: {run_id}")
- raise typer.Exit(1)
- except ValueError as exc:
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
+ 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)
- except Exception as exc:
- err.print(f"[red]Resume failed:[/red] {_escape_markup(str(exc))}")
+ 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)
- if json_output:
- _emit_workflow_json(_workflow_run_payload(state))
- raise typer.Exit(_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")
- console.print(f"\n[{color}]Status: {state.status.value}[/{color}]")
-
- err_msg = _failed_step_error(state)
- if err_msg:
- console.print(f"[red]Error:[/red] {_escape_markup(err_msg)}")
-
- raise typer.Exit(_run_outcome_exit_code(state.status.value))
-
-
-@workflow_app.command("status")
-def workflow_status(
- run_id: str | None = typer.Argument(None, help="Run ID to inspect (shows all if omitted)"),
- json_output: bool = typer.Option(
- False,
- "--json",
- help="Emit run status as a single JSON object instead of formatted text.",
- ),
-):
- """Show workflow run status."""
- from .engine import WorkflowEngine
-
- project_root = _require_specify_project()
- engine = WorkflowEngine(project_root)
-
- if run_id:
- # Route errors to stderr under --json so the stdout JSON stream stays
- # parseable (mirrors `workflow run`/`workflow resume`); both handlers
- # fire before the json_output branch below.
- err = _error_console(json_output)
- try:
- from .engine import RunState
- state = RunState.load(run_id, project_root)
- except FileNotFoundError:
- err.print(f"[red]Error:[/red] Run not found: {run_id}")
- raise typer.Exit(1)
- except ValueError as exc:
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- except OSError as exc:
- # An unreadable state.json (bad permissions, a directory in its
- # place, I/O error) must fail as cleanly as the malformed-JSON
- # case above -- `workflow resume` already handles OSError here.
- err.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
-
- if json_output:
- # Build on the shared run/resume payload so the common fields
- # (including current_step_index) stay identical across commands.
- payload = {
- **_workflow_run_payload(state),
- "created_at": state.created_at,
- "updated_at": state.updated_at,
- "steps": {
- sid: sd.get("status", "unknown")
- for sid, sd in state.step_results.items()
- },
- }
- _emit_workflow_json(payload)
- return
-
- status_colors = {
- "completed": "green",
- "paused": "yellow",
- "failed": "red",
- "aborted": "red",
- "running": "blue",
- "created": "dim",
- }
- color = status_colors.get(state.status.value, "white")
-
- console.print(f"\n[bold cyan]Workflow Run: {state.run_id}[/bold cyan]")
- console.print(f" Workflow: {state.workflow_id}")
- console.print(f" Status: [{color}]{state.status.value}[/{color}]")
- console.print(f" Created: {state.created_at}")
- console.print(f" Updated: {state.updated_at}")
-
- if state.current_step_id:
- console.print(f" Current: {state.current_step_id}")
-
- err_msg = _failed_step_error(state)
- if err_msg:
- console.print(f" [red]Error: {_escape_markup(err_msg)}[/red]")
-
- if state.step_results:
- console.print(f"\n [bold]Steps ({len(state.step_results)}):[/bold]")
- for step_id, step_data in state.step_results.items():
- s = step_data.get("status", "unknown")
- sc = {"completed": "green", "failed": "red", "paused": "yellow"}.get(s, "white")
- console.print(f" [{sc}]●[/{sc}] {step_id}: {s}")
- else:
- runs = engine.list_runs()
-
- if json_output:
- payload = {
- "runs": [
- {
- "run_id": r["run_id"],
- "workflow_id": r.get("workflow_id"),
- "status": r.get("status", "unknown"),
- "updated_at": r.get("updated_at"),
- }
- for r in runs
- ]
- }
- _emit_workflow_json(payload)
- return
-
- if not runs:
- console.print("[yellow]No workflow runs found.[/yellow]")
- return
-
- console.print("\n[bold cyan]Workflow Runs:[/bold cyan]\n")
- for run_data in runs:
- s = run_data.get("status", "unknown")
- sc = {"completed": "green", "failed": "red", "paused": "yellow", "running": "blue"}.get(s, "white")
- console.print(
- f" [{sc}]●[/{sc}] {run_data['run_id']} "
- f"{run_data.get('workflow_id', '?')} "
- f"[{sc}]{s}[/{sc}] "
- f"[dim]{run_data.get('updated_at', '?')}[/dim]"
- )
-
-
-@workflow_app.command("list")
-def workflow_list():
- """List installed workflows."""
- project_root = _require_specify_project()
- registry = _open_workflow_registry(project_root)
- installed = registry.list()
+ # 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"
- if not installed:
- console.print("[yellow]No workflows installed.[/yellow]")
- console.print("\nInstall a workflow with:")
- console.print(" [cyan]specify workflow add <workflow-id>[/cyan]")
- return
+ # 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()
- console.print("\n[bold cyan]Installed Workflows:[/bold cyan]\n")
- for wf_id, wf_data in installed.items():
- safe_id = _escape_markup(wf_id)
- if not isinstance(wf_data, dict):
- console.print(f" [yellow]Warning:[/yellow] Skipping corrupted registry entry '{safe_id}'.\n")
- continue
- marker = "" if wf_data.get("enabled", True) else " [red]\\[disabled][/red]"
- name = _escape_markup(str(wf_data.get("name", wf_id)))
- version = _escape_markup(str(wf_data.get("version", "?")))
- console.print(f" [bold]{name}[/bold] ({safe_id}) v{version}{marker}")
- desc = wf_data.get("description", "")
- if desc:
- console.print(f" {_escape_markup(str(desc))}")
- console.print()
-
-
-def _cleanup_download_tmp_path(tmp_path: Path | None) -> None:
- """Best-effort unlink of a partially-downloaded workflow temp file.
-
- A cleanup ``OSError`` here must never replace/mask whatever error or
- interrupt is already propagating -- warn about it and keep going.
- """
- if tmp_path is None:
- return
try:
- tmp_path.unlink(missing_ok=True)
- except OSError as cleanup_exc:
+ staged_file = _stage_workflow_file(
+ workflow_dir,
+ use_project_file_mode=not workflow_file.exists(),
+ )
+ except OSError as exc:
console.print(
- "[yellow]Warning:[/yellow] Could not remove temporary "
- f"workflow download file: {_escape_markup(str(cleanup_exc))} "
- f"(path: {_escape_markup(str(tmp_path))})"
+ 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._github_http import resolve_github_release_asset_api_url as _resolve_gh_asset
-@workflow_app.command("add")
-def workflow_add(
- source: str = typer.Argument(..., help="Workflow ID, URL, or local path"),
- dev: bool = typer.Option(False, "--dev", help="Install from a local workflow YAML file or directory"),
- from_url: str | None = typer.Option(None, "--from", help="Install from a custom URL"),
-):
- """Install a workflow from catalog, URL, or local path."""
- from . import load_custom_steps
- from .engine import WorkflowDefinition
-
- project_root = _require_specify_project()
- load_custom_steps(project_root)
- _open_workflow_registry(project_root)
- workflows_dir = project_root / ".specify" / "workflows"
- # With --from, source names the expected workflow ID: validate it up
- # front so a URL/path/typo fails without a network fetch.
- if from_url is not None and not dev:
- _validate_workflow_id_or_exit(source)
- # Reject a symlinked .specify / .specify/workflows before any write so an
- # install can't escape the project root (covers the local, URL, and
- # catalog branches below — all write beneath workflows_dir).
- _reject_unsafe_dir(project_root / ".specify", ".specify")
- _reject_unsafe_dir(workflows_dir, ".specify/workflows")
+ _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"}
- def _validate_and_install_local(
- yaml_path: Path, source_label: str, expected_id: str | None = None
- ) -> None:
- """Validate and install a workflow from a local YAML file."""
- try:
- with yaml_path.open("rb") as source_file:
- source_mode = os.fstat(source_file.fileno()).st_mode & 0o7777
- source_content = source_file.read()
- definition = WorkflowDefinition.from_string(
- source_content.decode("utf-8")
+ 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
)
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to read workflow YAML: "
- f"{_escape_markup(str(exc))}"
+ 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)
)
- raise typer.Exit(1)
- except (UnicodeDecodeError, ValueError, yaml.YAMLError) as exc:
- console.print(f"[red]Error:[/red] Invalid workflow YAML: {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- # Non-string ids (e.g. unquoted ``id: 123`` or ``id: 0``) fall through
- # to validate_workflow below, which reports a typed error instead of
- # crashing on ``.strip()`` here. Only None/empty/whitespace-only ids
- # are rejected as missing.
- if (
- definition.id is None
- or definition.id == ""
- or (isinstance(definition.id, str) and not definition.id.strip())
- ):
- console.print("[red]Error:[/red] Workflow definition has an empty or missing 'id'")
- raise typer.Exit(1)
-
- from .engine import validate_workflow
- errors = validate_workflow(definition)
- if errors:
- console.print("[red]Error:[/red] Workflow validation failed:")
- for err in errors:
- console.print(f" \u2022 {_escape_markup(str(err))}")
- 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 ({_escape_markup(repr(definition.id))}) "
- f"does not match the requested workflow ID ({_escape_markup(repr(expected_id))})."
- )
- raise typer.Exit(1)
-
- dest_dir = _safe_workflow_id_dir(workflows_dir, definition.id)
- dest_file = dest_dir / "workflow.yml"
- existed_before = dest_dir.is_dir()
-
- try:
- staged_file = _stage_workflow_file(dest_dir)
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to install workflow "
- f"'{_escape_markup(definition.id)}': {_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
-
- try:
- # Write the exact bytes parsed above so a concurrent source edit
- # cannot desynchronize installed content from validated metadata.
- staged_file.write_bytes(source_content)
- staged_file.set_mode(source_mode)
- except OSError as exc:
- _safe_discard_staged_workflow_file(staged_file, dest_dir, existed_before)
- console.print(
- f"[red]Error:[/red] Failed to install workflow "
- f"'{_escape_markup(definition.id)}': {_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
-
- try:
- transaction = _workflow_install_transaction(project_root)
- with transaction:
- transaction_existed_before = existed_before or dest_file.exists()
- transaction_registry = _open_workflow_registry(project_root)
- # Commit the staged copy onto dest_file via an atomic swap. A
- # prior file is renamed aside so registry failure can restore it.
- try:
- backup_file = _commit_workflow_file(
- staged_file, dest_file, transaction_existed_before
- )
- except OSError as exc:
- _safe_discard_staged_workflow_file(
- staged_file, dest_dir, existed_before
- )
- console.print(
- f"[red]Error:[/red] Failed to install workflow "
- f"'{_escape_markup(definition.id)}': "
- f"{_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- try:
- entry = {
- "name": definition.name,
- "version": definition.version,
- "description": definition.description,
- "source": source_label,
- }
- existing = transaction_registry.get(definition.id)
- if isinstance(existing, dict) and not existing.get(
- "enabled", True
- ):
- entry["enabled"] = False
- transaction_registry.add(definition.id, entry)
- except (OSError, TypeError, ValueError) as exc:
- _safe_rollback_committed_workflow_file(
- dest_file,
- dest_dir,
- transaction_existed_before,
- backup_file,
- )
- console.print(
- f"[red]Error:[/red] Failed to update workflow registry for "
- f"'{_escape_markup(definition.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, dest_dir, existed_before
- )
- raise
- except OSError as exc:
- _safe_discard_staged_workflow_file(staged_file, dest_dir, existed_before)
- console.print(
- f"[red]Error:[/red] Failed to lock workflow install "
- f"'{_escape_markup(definition.id)}': {_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- console.print(
- f"[green]✓[/green] Workflow '{_escape_markup(definition.name)}' "
- f"({_escape_markup(definition.id)}) installed"
- )
-
- # Explicit local install (mirrors `extension add --dev`). --dev takes
- # precedence over --from so a URL that would be ignored is never fetched.
- if dev:
- dev_path = Path(source).expanduser()
- if dev_path.is_file() and dev_path.suffix.lower() in (".yml", ".yaml"):
- _validate_and_install_local(dev_path, str(dev_path))
- return
- if dev_path.is_file() and archive_format_from_name(str(dev_path)) is not None:
- import tempfile
-
- with tempfile.TemporaryDirectory(
- prefix="speckit-workflow-archive-"
- ) as tmpdir:
- extracted_root = Path(tmpdir)
- try:
- safe_extract_archive(dev_path, extracted_root)
- package_root = _workflow_package_root(extracted_root)
- except ValueError as exc:
- console.print(
- f"[red]Error:[/red] Invalid workflow archive: "
- f"{_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- _install_workflow_package(
- project_root,
- workflows_dir,
- package_root,
- str(dev_path),
- )
- return
- if dev_path.is_dir():
- dev_wf_file = dev_path / "workflow.yml"
- if not dev_wf_file.is_file():
- console.print(f"[red]Error:[/red] No workflow.yml found in {_escape_markup(source)}")
- raise typer.Exit(1)
- if _workflow_package_has_companions(dev_path):
- _install_workflow_package(
- project_root,
- workflows_dir,
- dev_path,
- str(dev_path),
+ # 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:
- _validate_and_install_local(dev_wf_file, str(dev_path))
- return
- console.print(
- "[red]Error:[/red] --dev source must be a workflow YAML file, "
- "supported archive, or directory containing workflow.yml: "
- f"{_escape_markup(source)}"
- )
+ 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 as URL (http/https) — either the positional source is a URL, or an
- # explicit --from URL names where to fetch it (mirrors `extension add --from`).
- download_url = (
- from_url
- if from_url is not None
- else (source if source.startswith(("http://", "https://")) else None)
- )
- if download_url is not None:
- from urllib.parse import urlparse
- from specify_cli.authentication.http import open_url as _open_url
-
+ if downloaded_archive_format is not None:
try:
- urlparse(download_url).port
- except ValueError:
- console.print(f"[red]Error:[/red] Invalid URL: {_escape_markup(download_url)}")
- raise typer.Exit(1)
- if not is_https_or_localhost_http(download_url):
- console.print("[red]Error:[/red] Only HTTPS URLs are allowed, except HTTP for localhost.")
- raise typer.Exit(1)
-
- if from_url is not None:
- from rich.panel import Panel
-
- safe_url = _escape_markup(from_url)
- console.print()
- console.print(
- Panel(
- "[bold]You are installing a workflow from an external URL "
- "that is not\nlisted in any of your configured workflow "
- "catalogs.[/bold]\n\n"
- f"URL: {safe_url}\n\n"
- "Only install workflows from sources you trust.",
- title="[bold yellow]⚠ Untrusted Source[/bold yellow]",
- border_style="yellow",
- padding=(1, 2),
- )
+ verify_archive_sha256(
+ downloaded_content,
+ info.get("sha256"),
+ workflow_id,
+ ValueError,
)
- console.print()
- if not typer.confirm("Continue with installation?", default=False):
- console.print("Cancelled")
- raise typer.Exit(0)
-
- from specify_cli._github_http import resolve_github_release_asset_api_url as _resolve_gh_asset
- from specify_cli.authentication.http import github_provider_hosts as _github_provider_hosts
-
- _wf_url_extra_headers = None
- _resolved_wf_url = _resolve_gh_asset(
- download_url,
- _open_url,
- timeout=30,
- github_hosts=_github_provider_hosts(),
- redirect_validator=_reject_insecure_download_redirect,
- )
- if _resolved_wf_url:
- download_url = _resolved_wf_url
- _wf_url_extra_headers = {"Accept": "application/octet-stream"}
-
- import tempfile
- tmp_path: Path | None = None
- downloaded_archive_format = None
- try:
- with _open_url(
- download_url,
- timeout=30,
- extra_headers=_wf_url_extra_headers,
- redirect_validator=_reject_insecure_download_redirect,
- ) as resp:
- final_url = resp.geturl()
- if not is_https_or_localhost_http(final_url):
- console.print(
- f"[red]Error:[/red] URL redirected to non-HTTPS: {_escape_markup(final_url)}"
- )
- raise typer.Exit(1)
- content_type = (
- resp.getheader("Content-Type")
- if hasattr(resp, "getheader")
- else None
- )
- downloaded_archive_format = (
- archive_format_from_name(final_url)
- or archive_format_from_name(download_url)
- or archive_format_from_content_type(content_type)
- )
- declared_yaml = _workflow_yaml_is_declared(final_url, content_type)
- suffix = (
- archive_suffix(downloaded_archive_format)
- if downloaded_archive_format is not None
- else ".yml" if declared_yaml else ".download"
- )
- with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
- # Assign tmp_path immediately: NamedTemporaryFile(delete=False)
- # creates the file on disk right away, before any bytes are
- # written, so a failure in the size-limited read below must
- # still be able to find and remove it.
- tmp_path = Path(tmp.name)
- if downloaded_archive_format is not None:
- downloaded_content = read_response_limited(
- resp,
- error_type=ValueError,
- label="workflow archive download",
- )
- elif declared_yaml:
- downloaded_content = _read_response_within_limit(resp)
- else:
- downloaded_content = read_response_limited(
- resp,
- error_type=ValueError,
- label="workflow download",
- )
- downloaded_archive_format = (
- _sniff_workflow_archive_format(downloaded_content)
- )
- if downloaded_archive_format is None:
- _enforce_workflow_yaml_size(downloaded_content)
- tmp.write(downloaded_content)
- except typer.Exit:
- _cleanup_download_tmp_path(tmp_path)
- raise
- except Exception as exc:
- # A cleanup failure here must never replace/mask the
- # original download error below with a raw, unhandled
- # OSError -- warn about it and keep going, exactly like the
- # later post-install finally cleanup does.
- _cleanup_download_tmp_path(tmp_path)
- console.print(f"[red]Error:[/red] Failed to download workflow: {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- except BaseException:
- # Covers KeyboardInterrupt and other non-Exception exits: the
- # temp file is already created on disk (delete=False) by this
- # point, so an interrupt during the size-limited read must still
- # unlink it rather than leaking it to the system temp directory.
- _cleanup_download_tmp_path(tmp_path)
- raise
- try:
- if downloaded_archive_format is None:
- _validate_and_install_local(
- tmp_path,
- download_url,
- expected_id=source if from_url else None,
- )
- else:
- with tempfile.TemporaryDirectory(
- prefix="speckit-workflow-archive-"
- ) as extract_dir:
- extracted_root = Path(extract_dir)
- try:
- safe_extract_archive(
- tmp_path,
- extracted_root,
- source_name=final_url,
- content_type=content_type,
- )
- package_root = _workflow_package_root(extracted_root)
- except ValueError as exc:
- console.print(
- f"[red]Error:[/red] Invalid workflow archive: "
- f"{_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- _install_workflow_package(
- project_root,
- workflows_dir,
- package_root,
- download_url,
- expected_id=source if from_url else None,
- )
- finally:
- # Best-effort: _validate_and_install_local may already have
- # committed the file + registry entry (success) or already
- # raised its own clean typer.Exit (failure) by this point --
- # either way, a cleanup OSError here must never mask that
- # outcome or surface as its own unhandled failure. Warn instead,
- # same as the committed-backup cleanup above.
- try:
- tmp_path.unlink(missing_ok=True)
- except OSError as exc:
- console.print(
- "[yellow]Warning:[/yellow] Could not remove temporary "
- f"workflow download file: {_escape_markup(str(exc))} "
- f"(path: {_escape_markup(str(tmp_path))})"
- )
- return
-
- # Try as a local file/directory
- source_path = Path(source)
- if source_path.exists():
- if source_path.is_file() and source_path.suffix.lower() in (".yml", ".yaml"):
- _validate_and_install_local(source_path, str(source_path))
- return
- elif (
- source_path.is_file()
- and archive_format_from_name(str(source_path)) is not None
- ):
import tempfile
+ from io import BytesIO
with tempfile.TemporaryDirectory(
prefix="speckit-workflow-archive-"
- ) as tmpdir:
- extracted_root = Path(tmpdir)
- try:
- safe_extract_archive(source_path, extracted_root)
- package_root = _workflow_package_root(extracted_root)
- except ValueError as exc:
- console.print(
- f"[red]Error:[/red] Invalid workflow archive: "
- f"{_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- _install_workflow_package(
- project_root,
- workflows_dir,
- package_root,
- str(source_path),
+ ) 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,
)
- return
- elif source_path.is_dir():
- wf_file = source_path / "workflow.yml"
- if not wf_file.is_file():
- console.print(f"[red]Error:[/red] No workflow.yml found in {_escape_markup(source)}")
- raise typer.Exit(1)
- if _workflow_package_has_companions(source_path):
_install_workflow_package(
project_root,
workflows_dir,
- source_path,
- str(source_path),
+ package_root,
+ workflow_url,
+ expected_id=workflow_id,
+ expected_version=expected_version,
+ expected_installed_version=expected_installed_version,
+ catalog_info={**info, "url": workflow_url},
)
- else:
- _validate_and_install_local(wf_file, str(source_path))
- return
-
- # Try from catalog
- _install_workflow_from_catalog(project_root, workflows_dir, source)
-
-
-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,
-) -> 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.
- """
- from .catalog import WorkflowCatalog, WorkflowCatalogError
- from .engine import WorkflowDefinition
-
- def versions_match(actual: object, expected: str) -> bool:
- from packaging import version as pkg_version
-
- try:
- return pkg_version.Version(str(actual)) == pkg_version.Version(
- expected
+ except typer.Exit:
+ raise
+ except (OSError, ValueError) as exc:
+ _safe_discard_staged_workflow_file(
+ staged_file,
+ workflow_dir,
+ existed_before,
)
- except pkg_version.InvalidVersion:
- return str(actual) == expected
-
- safe_wf_id = _escape_markup(workflow_id)
+ console.print(
+ f"[red]Error:[/red] Invalid workflow archive: "
+ f"{_escape_markup(str(exc))}"
+ )
+ raise typer.Exit(1)
+ return
- catalog = WorkflowCatalog(project_root)
+ # Validate the downloaded workflow (still staged, not yet committed)
+ # before registering.
try:
- info = 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:
- console.print(f"[red]Error:[/red] Workflow '{safe_wf_id}' not found in catalog")
+ 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)
- 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._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)
-
- if downloaded_archive_format is not None:
- try:
- verify_archive_sha256(
- downloaded_content,
- info.get("sha256"),
- workflow_id,
- ValueError,
- )
- 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_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))}")
+ 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:
- if not 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)
-
- 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 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 _remove_workflow_locked(
- project_root: Path, workflows_dir: Path, workflow_id: str
-) -> Path | None:
- """Stage a workflow directory and persist removal while locked."""
- registry = _open_workflow_registry(project_root)
- safe_id = _escape_markup(workflow_id)
- if not registry.is_installed(workflow_id):
- console.print(
- f"[red]Error:[/red] Workflow '{safe_id}' is not installed"
- )
- raise typer.Exit(1)
-
- workflow_dir_unresolved = workflows_dir / workflow_id
- if workflow_dir_unresolved.is_symlink():
- console.print(
- f"[red]Error:[/red] Refusing to remove symlinked "
- f".specify/workflows/{safe_id}"
- )
- raise typer.Exit(1)
-
- workflow_dir = workflow_dir_unresolved.resolve()
- try:
- rel_parts = workflow_dir.relative_to(workflows_dir.resolve()).parts
- except ValueError:
- console.print(
- f"[red]Error:[/red] Invalid workflow ID: "
- f"{_escape_markup(repr(workflow_id))}"
- )
- raise typer.Exit(1)
- if rel_parts != (workflow_id,):
- console.print(
- f"[red]Error:[/red] Invalid workflow ID: "
- f"{_escape_markup(repr(workflow_id))}"
- )
- raise typer.Exit(1)
-
- if workflow_dir.exists() and not workflow_dir.is_dir():
- console.print(
- f"[red]Error:[/red] .specify/workflows/{safe_id} exists "
- "but is not a directory"
- )
- raise typer.Exit(1)
-
- import tempfile
-
- staged_dir: Path | None = None
- if workflow_dir.exists():
- try:
- reserved = Path(
- tempfile.mkdtemp(
- prefix=f".{workflow_id}.removing-", dir=workflows_dir
- )
- )
- reserved.rmdir()
- os.rename(workflow_dir, reserved)
- staged_dir = reserved
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to stage workflow directory "
- f"{_escape_markup(str(workflow_dir))} for removal: "
- f"{_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
-
- try:
- registry.remove(workflow_id)
- except (OSError, TypeError, ValueError) as exc:
- if staged_dir is not None:
- try:
- os.rename(staged_dir, workflow_dir)
- except OSError as restore_exc:
- console.print(
- f"[yellow]Warning:[/yellow] Failed to restore workflow "
- "directory after registry update failure; it remains "
- f"staged at {_escape_markup(str(staged_dir))}: "
- f"{_escape_markup(str(restore_exc))}"
- )
- console.print(
- f"[red]Error:[/red] Failed to update workflow registry for "
- f"'{safe_id}': {_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
- return staged_dir
-
-
-@workflow_app.command("remove")
-def workflow_remove(
- workflow_id: str = typer.Argument(..., help="Workflow ID to uninstall"),
-):
- """Uninstall a workflow."""
- project_root = _require_specify_project()
- workflows_dir = project_root / ".specify" / "workflows"
- _validate_workflow_id_or_exit(workflow_id)
- safe_id = _escape_markup(workflow_id)
- import shutil
- try:
- with _workflow_install_transaction(project_root):
- staged_dir = _remove_workflow_locked(
- project_root, workflows_dir, workflow_id
- )
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to lock workflow removal "
- f"'{safe_id}': {_escape_markup(str(exc))}"
- )
- raise typer.Exit(1)
-
- console.print(f"[green]✓[/green] Workflow '{workflow_id}' removed")
-
- # The registry has already durably committed the removal at this point,
- # so it must stand regardless of what happens below: deleting the staged
- # directory is now just cleanup, not a data-integrity concern, and a
- # failure here is reported as a warning (not an error) to avoid
- # contradicting the registry state that already succeeded.
- if staged_dir is not None:
- try:
- shutil.rmtree(staged_dir)
- except OSError as exc:
- console.print(
- f"[yellow]Warning:[/yellow] Workflow '{safe_id}' was removed, but its "
- f"staged directory could not be deleted: {_escape_markup(str(exc))}. "
- f"Remove it manually: {_escape_markup(str(staged_dir))}"
- )
-
-
-@workflow_app.command("update")
-def workflow_update(
- workflow_id: str | None = typer.Argument(None, help="Workflow ID to update (default: all)"),
-):
- """Update installed workflow(s) to the latest catalog version."""
- from packaging import version as pkg_version
-
- from .catalog import WorkflowCatalog, WorkflowCatalogError
-
- project_root = _require_specify_project()
- registry = _open_workflow_registry(project_root)
- workflows_dir = project_root / ".specify" / "workflows"
- _reject_unsafe_dir(project_root / ".specify", ".specify")
- _reject_unsafe_dir(workflows_dir, ".specify/workflows")
-
- installed = registry.list()
- if workflow_id:
- if not registry.is_installed(workflow_id):
- console.print(f"[red]Error:[/red] Workflow '{_escape_markup(workflow_id)}' is not installed")
- raise typer.Exit(1)
- targets = [workflow_id]
- else:
- targets = list(installed)
-
- if not targets:
- console.print("[yellow]No workflows installed[/yellow]")
- raise typer.Exit(0)
-
- catalog = WorkflowCatalog(project_root)
- console.print("🔄 Checking for updates...\n")
-
- updates_available: list[dict[str, str]] = []
- checked = 0
- for wf_id in targets:
- safe_id = _escape_markup(str(wf_id))
- metadata = installed.get(wf_id)
- if not isinstance(metadata, dict):
- console.print(f"⚠ {safe_id}: Registry entry is corrupted (skipping)")
- continue
- if metadata.get("source") != "catalog":
- console.print(f"⚠ {safe_id}: Not installed from a catalog — re-add to update (skipping)")
- continue
- try:
- installed_version = pkg_version.Version(str(metadata.get("version")))
- except pkg_version.InvalidVersion:
- console.print(
- f"⚠ {safe_id}: Invalid installed version '{_escape_markup(str(metadata.get('version')))}' in registry (skipping)"
- )
- continue
- try:
- info = catalog.get_workflow_info(wf_id)
- except WorkflowCatalogError as exc:
- console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
- if not info:
- console.print(f"⚠ {safe_id}: Not found in catalog (skipping)")
- continue
- if not info.get("_install_allowed", True):
- console.print(
- f"⚠ {safe_id}: Updates not allowed from '{_escape_markup(str(info.get('_catalog_name', 'catalog')))}' (skipping)"
- )
- continue
- try:
- catalog_version = pkg_version.Version(str(info.get("version")))
- except pkg_version.InvalidVersion:
- console.print(
- f"⚠ {safe_id}: Invalid catalog version '{_escape_markup(str(info.get('version')))}' (skipping)"
- )
- continue
- if catalog_version > installed_version:
- checked += 1
- updates_available.append(
- {"id": wf_id, "installed": str(installed_version), "available": str(catalog_version)}
- )
- else:
- checked += 1
- console.print(f"✓ {safe_id}: Up to date (v{installed_version})")
-
- if not updates_available:
- if not checked:
- console.print("\n[yellow]No workflows were eligible for update[/yellow]")
- elif checked == len(targets):
- console.print("\n[green]All workflows are up to date![/green]")
- else:
- console.print(
- f"\n[green]All checked workflows are up to date[/green] "
- f"[yellow]({len(targets) - checked} skipped)[/yellow]"
- )
- raise typer.Exit(0)
-
- console.print("\n[bold]Updates available:[/bold]\n")
- for update in updates_available:
- console.print(
- f" • {_escape_markup(update['id'])}: {update['installed']} → {update['available']}"
- )
- console.print()
- if not typer.confirm("Update these workflows?"):
- console.print("Cancelled")
- raise typer.Exit(0)
-
- console.print()
- failed: list[str] = []
- for update in updates_available:
- # _install_workflow_from_catalog is fully transactional (staged
- # download, atomic commit, rename-based rollback on registry
- # failure): it never leaves a partially-written workflow.yml, so
- # this loop only needs to record success/failure, not perform its
- # own backup/restore.
- try:
- _install_workflow_from_catalog(
- project_root, workflows_dir, update["id"],
- expected_version=update["available"],
- expected_installed_version=update["installed"],
- )
- except (typer.Exit, OSError) as exc:
- if isinstance(exc, OSError):
- console.print(
- f"[red]Error:[/red] Filesystem error updating "
- f"'{_escape_markup(update['id'])}': {_escape_markup(str(exc))}"
- )
- failed.append(update["id"])
-
- if failed:
- console.print(
- f"\n[red]Failed to update:[/red] {', '.join(_escape_markup(f) for f in failed)}"
- )
- raise typer.Exit(1)
-
-
-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}")
-
-
-@workflow_app.command("enable")
-def workflow_enable(
- workflow_id: str = typer.Argument(..., help="Workflow ID to enable"),
-):
- """Enable a disabled workflow."""
- _set_workflow_enabled(workflow_id, True)
-
-
-@workflow_app.command("disable")
-def workflow_disable(
- workflow_id: str = typer.Argument(..., help="Workflow ID to disable"),
-):
- """Disable a workflow without removing it."""
- _set_workflow_enabled(workflow_id, False)
- console.print(f"To re-enable: specify workflow enable {_escape_markup(workflow_id)}")
-
-
-@workflow_app.command("search")
-def workflow_search(
- query: str | None = typer.Argument(None, help="Search query"),
- tag: str | None = typer.Option(None, "--tag", help="Filter by tag"),
- author: str | None = typer.Option(None, "--author", help="Filter by author"),
-):
- """Search workflow catalogs."""
- from .catalog import WorkflowCatalog, WorkflowCatalogError
-
- project_root = _require_specify_project()
- catalog = WorkflowCatalog(project_root)
-
- try:
- results = catalog.search(query=query, tag=tag, author=author)
- except WorkflowCatalogError as exc:
- console.print(f"[red]Error:[/red] {_escape_markup(str(exc))}")
- raise typer.Exit(1)
-
- if not results:
- console.print("[yellow]No workflows found.[/yellow]")
- return
-
- console.print(f"\n[bold cyan]Workflows ({len(results)}):[/bold cyan]\n")
- for wf in results:
- name = _escape_markup(str(wf.get("name", wf.get("id", "?"))))
- wf_id = _escape_markup(str(wf.get("id", "?")))
- version = _escape_markup(str(wf.get("version", "?")))
- console.print(f" [bold]{name}[/bold] ({wf_id}) v{version}")
- desc = wf.get("description", "")
- if desc:
- console.print(f" {_escape_markup(str(desc))}")
- tags = wf.get("tags", [])
- if isinstance(tags, list) and tags:
- safe_tags = _escape_markup(", ".join(str(t) for t in tags))
- console.print(f" [dim]Tags: {safe_tags}[/dim]")
- console.print()
-
-
-@workflow_app.command("info")
-def workflow_info(
- workflow_id: str = typer.Argument(..., help="Workflow ID"),
-):
- """Show workflow details and step graph."""
- from .catalog import WorkflowCatalog, WorkflowCatalogError
- from .engine import WorkflowEngine
-
- project_root = _require_specify_project()
-
- # Check installed first
- registry = _open_workflow_registry(project_root)
- installed = registry.get(workflow_id)
-
- engine = WorkflowEngine(project_root)
-
- definition = None
- try:
- definition = engine.load_workflow(workflow_id)
- except FileNotFoundError:
- # Local workflow definition not found on disk; fall back to
- # catalog/registry lookup below.
- pass
- except ValueError as exc:
- console.print(f"[red]Error:[/red] Invalid workflow: {_escape_markup(str(exc))}")
- raise typer.Exit(1)
-
- if definition:
- # Escape every user-controlled field: workflow.yml values (name,
- # version, author, description, integration, input names/types) are not
- # trusted, and console.print has Rich markup enabled, so an unescaped
- # `[...]` in any of them is parsed as a style tag and silently swallowed
- # (same defect fixed for the step graph below; the sibling workflow_list
- # already escapes all of these).
- console.print(
- f"\n[bold cyan]{_escape_markup(str(definition.name))}[/bold cyan] "
- f"({_escape_markup(str(definition.id))})"
- )
- console.print(f" Version: {_escape_markup(str(definition.version))}")
- if definition.author:
- console.print(f" Author: {_escape_markup(str(definition.author))}")
- if definition.description:
- console.print(f" Description: {_escape_markup(str(definition.description))}")
- if definition.default_integration:
- console.print(
- f" Integration: {_escape_markup(str(definition.default_integration))}"
- )
- if installed:
- console.print(" [green]Installed[/green]")
-
- if definition.inputs:
- console.print("\n [bold]Inputs:[/bold]")
- for name, inp in definition.inputs.items():
- if isinstance(inp, dict):
- req = "required" if inp.get("required") else "optional"
- console.print(
- f" {_escape_markup(str(name))} "
- f"({_escape_markup(str(inp.get('type', 'string')))}) — {req}"
- )
-
- if definition.steps:
- console.print(f"\n [bold]Steps ({len(definition.steps)}):[/bold]")
- for step in definition.steps:
- stype = step.get("type", "command")
- # Escape the literal bracket (\[) so Rich renders `[<type>]`
- # instead of parsing it as a style tag named after the step
- # type (which it silently swallows); escape id/type too, as
- # the sibling workflow_list does. Mirrors the `\[disabled]`
- # precedent above.
- console.print(
- f" → {_escape_markup(str(step.get('id', '?')))} "
- f"\\[{_escape_markup(str(stype))}]"
- )
- return
-
- # Try catalog
- catalog = WorkflowCatalog(project_root)
- try:
- info = catalog.get_workflow_info(workflow_id)
- except WorkflowCatalogError:
- info = None
-
- if info:
- # Catalog-derived fields are untrusted; escape them so bracketed content
- # is rendered literally rather than parsed (and swallowed) as Rich markup.
- console.print(
- f"\n[bold cyan]{_escape_markup(str(info.get('name', workflow_id)))}[/bold cyan] "
- f"({_escape_markup(str(workflow_id))})"
- )
- console.print(f" Version: {_escape_markup(str(info.get('version', '?')))}")
- if info.get("description"):
- console.print(f" Description: {_escape_markup(str(info['description']))}")
- info_tags = info.get("tags", [])
- if isinstance(info_tags, list) and info_tags:
- safe_tags = _escape_markup(", ".join(str(t) for t in info_tags))
- console.print(f" Tags: {safe_tags}")
- console.print(" [yellow]Not installed[/yellow]")
- else:
- console.print(
- f"[red]Error:[/red] Workflow '{_escape_markup(str(workflow_id))}' not found"
- )
- raise typer.Exit(1)
-
-
-@workflow_catalog_app.command("list")
-def workflow_catalog_list():
- """List configured workflow catalog sources."""
- from .catalog import WorkflowCatalog, WorkflowCatalogError
-
- project_root = _require_specify_project()
- catalog = WorkflowCatalog(project_root)
-
- try:
- configs = catalog.get_catalog_configs()
- except WorkflowCatalogError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- console.print("\n[bold cyan]Workflow Catalog Sources:[/bold cyan]\n")
- for i, cfg in enumerate(configs):
- install_status = "[green]install allowed[/green]" if cfg["install_allowed"] else "[yellow]discovery only[/yellow]"
- console.print(f" [{i}] [bold]{_escape_markup(str(cfg['name']))}[/bold] — {install_status}")
- console.print(f" {_escape_markup(str(cfg['url']))}")
- if cfg.get("description"):
- console.print(f" [dim]{_escape_markup(str(cfg['description']))}[/dim]")
- console.print()
-
-
-@workflow_catalog_app.command("add")
-def workflow_catalog_add(
- url: str = typer.Argument(..., help="Catalog URL to add"),
- name: str | None = typer.Option(None, "--name", help="Catalog name"),
-):
- """Add a workflow catalog source."""
- from .catalog import WorkflowCatalog, WorkflowValidationError
-
- project_root = _require_specify_project()
- catalog = WorkflowCatalog(project_root)
- try:
- catalog.add_catalog(url, name)
- except WorkflowValidationError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- console.print(f"[green]✓[/green] Catalog source added: {url}")
-
-
-@workflow_catalog_app.command("remove")
-def workflow_catalog_remove(
- index: int = typer.Argument(..., help="Catalog index to remove (from 'catalog list')"),
-):
- """Remove a workflow catalog source by index."""
- from .catalog import WorkflowCatalog, WorkflowValidationError
-
- project_root = _require_specify_project()
- catalog = WorkflowCatalog(project_root)
- try:
- removed_name = catalog.remove_catalog(index)
- except WorkflowValidationError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- console.print(f"[green]✓[/green] Catalog source '{removed_name}' removed")
-
-
-# ===== Workflow Step Commands =====
-
-@workflow_step_app.command("list")
-def workflow_step_list():
- """List installed step types (built-in and custom)."""
- from . import STEP_REGISTRY
- from .catalog import StepRegistry
-
- project_root = _require_specify_project()
- specify_dir = project_root / ".specify"
-
- # Read installed custom steps from registry only — no dynamic imports
- installed: dict = {}
- if specify_dir.exists():
- registry = StepRegistry(project_root)
- installed = registry.list()
-
- console.print("\n[bold cyan]Installed Step Types:[/bold cyan]\n")
-
- built_in = sorted(k for k in STEP_REGISTRY if k not in installed)
- if built_in:
- console.print(" [bold]Built-in:[/bold]")
- for key in built_in:
- console.print(f" • {key}")
- console.print()
-
- if installed:
- console.print(" [bold]Custom (installed):[/bold]")
- for key in sorted(installed):
- meta = installed[key] or {}
- name = _escape_markup(str(meta.get("name", key)))
- safe_key = _escape_markup(str(key))
- version = _escape_markup(str(meta.get("version", "?")))
- console.print(f" • [bold]{name}[/bold] ({safe_key}) v{version}")
- console.print()
-
- if not built_in and not installed:
- console.print("[yellow]No step types found.[/yellow]")
-
- if specify_dir.exists():
- console.print(
- " Install a new step type with: [cyan]specify workflow step add <id>[/cyan]"
- )
-
-
-# IDs that map to internal names used under .specify/workflows/steps/ and must
-# not be used as custom step IDs (dotfile check is done separately at runtime).
-_RESERVED_STEP_IDS: frozenset[str] = frozenset({".cache", "step-registry.json"})
-
-# Windows reserved device names (case-insensitive, with or without extensions)
-_WINDOWS_RESERVED_NAMES: frozenset[str] = frozenset({
- "con", "prn", "aux", "nul",
- "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9",
- "lpt1", "lpt2", "lpt3", "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9",
-})
-
-# Characters invalid in filenames on Windows
-_WINDOWS_INVALID_CHARS: frozenset[str] = frozenset('<>:"|?*')
-
-
-def _validate_step_id_or_exit(step_id: str) -> None:
- """Validate that ``step_id`` is a single safe path component.
-
- Rejects empty strings, whitespace-only strings, leading/trailing whitespace,
- path separators, ``.``/``..`` components, dotfile prefixes, reserved names,
- Windows-invalid filename characters, trailing dots/spaces, and Windows
- reserved device names. Exits with code 1 on failure.
- """
- # Strip the stem (before first dot) for Windows reserved-name check
- stem = step_id.split(".")[0].lower() if step_id else ""
- if (
- not step_id
- or not step_id.strip()
- or step_id != step_id.strip()
- or "/" in step_id
- or "\\" in step_id
- or step_id in (".", "..")
- or step_id.startswith(".")
- or step_id.endswith(".")
- or step_id.endswith(" ")
- or step_id.lower() in _RESERVED_STEP_IDS
- or stem in _WINDOWS_RESERVED_NAMES
- or any(c in _WINDOWS_INVALID_CHARS for c in step_id)
- or any(ord(c) < 32 for c in step_id)
- ):
- console.print(
- f"[red]Error:[/red] Invalid step id '{step_id}': must be a single safe "
- "path component (no separators, no leading dot, not a reserved name, "
- "no invalid filename characters)"
- )
- raise typer.Exit(1)
-
-
-def _resolve_steps_base_dir_or_exit(project_root: Path) -> Path:
- """Resolve .specify/workflows/steps while refusing symlinked parent directories."""
- project_root_resolved = project_root.resolve()
- steps_base_dir_unresolved = project_root / ".specify" / "workflows" / "steps"
-
- current = project_root
- for part in (".specify", "workflows", "steps"):
- current = current / part
- if current.is_symlink():
- console.print(
- f"[red]Error:[/red] Refusing to use symlinked step directory '{current}'"
- )
- raise typer.Exit(1)
- if current.exists() and not current.is_dir():
- console.print(
- f"[red]Error:[/red] Step directory path is not a directory: '{current}'"
- )
- raise typer.Exit(1)
-
- steps_base_dir = steps_base_dir_unresolved.resolve()
- try:
- steps_base_dir.relative_to(project_root_resolved)
- except ValueError:
- console.print(
- f"[red]Error:[/red] Step directory escapes project root: '{steps_base_dir}'"
- )
- raise typer.Exit(1)
-
- return steps_base_dir
-
-
-@workflow_step_app.command("add")
-def workflow_step_add(
- step_id: str = typer.Argument(..., help="Step type ID from catalog"),
-):
- """Install a custom step type from the step catalog."""
- from .catalog import StepCatalog, StepCatalogError, StepRegistry, StepValidationError
-
- project_root = _require_specify_project()
-
- catalog = StepCatalog(project_root)
- try:
- info = catalog.get_step_info(step_id)
- except StepCatalogError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- if not info:
- console.print(f"[red]Error:[/red] Step type '{step_id}' not found in catalog")
- raise typer.Exit(1)
-
- if not info.get("_install_allowed", True):
- console.print(
- f"[yellow]Warning:[/yellow] Step type '{step_id}' is from a discovery-only catalog"
- )
- console.print("Direct installation is not enabled for this catalog source.")
- raise typer.Exit(1)
-
- # Reject step IDs that collide with built-in step types
- from . import STEP_REGISTRY as _step_reg
- if step_id in _step_reg:
- console.print(
- f"[red]Error:[/red] Step type '{step_id}' conflicts with a built-in step type"
- )
- raise typer.Exit(1)
-
- # Reject if already installed
- registry = StepRegistry(project_root)
- if registry.is_installed(step_id):
- console.print(
- f"[red]Error:[/red] Step type '{step_id}' is already installed. "
- "Remove it first with: [cyan]specify workflow step remove "
- f"{step_id}[/cyan]"
- )
- raise typer.Exit(1)
-
- declared_step_yml_url = info.get("step_yml_url")
- if declared_step_yml_url is not None and not isinstance(
- declared_step_yml_url, str
- ):
- console.print(
- f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
- "step.yml URL; expected a non-empty string"
- )
- raise typer.Exit(1)
- step_yml_url = declared_step_yml_url or info.get("url")
- if step_yml_url is None or (
- isinstance(step_yml_url, str) and not step_yml_url.strip()
- ):
- console.print(f"[red]Error:[/red] Catalog entry for '{step_id}' has no URL")
- raise typer.Exit(1)
- if not isinstance(step_yml_url, str):
- console.print(
- f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
- "step.yml URL; expected a non-empty string"
- )
- raise typer.Exit(1)
-
- # Derive __init__.py URL: replace trailing step.yml with __init__.py
- # or use explicit init_url if provided.
- init_url = info.get("init_url")
- if init_url is not None and (
- not isinstance(init_url, str) or not init_url.strip()
- ):
- console.print(
- f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
- "__init__.py URL; expected a non-empty string"
- )
- raise typer.Exit(1)
- if not init_url:
- if step_yml_url.endswith("step.yml"):
- init_url = step_yml_url[: -len("step.yml")] + "__init__.py"
- else:
- console.print(
- f"[red]Error:[/red] Cannot derive __init__.py URL from '{step_yml_url}'. "
- "Catalog entry should provide 'init_url' or a 'url' ending in 'step.yml'."
- )
- raise typer.Exit(1)
-
- # Preflight the declared file count before creating a staging directory or
- # issuing any request. The two required files are always part of the package;
- # duplicate declarations for them in extra_files are ignored below and do
- # not count twice.
- extra_files = info.get("extra_files")
- if extra_files is not None and not isinstance(extra_files, dict):
- console.print(
- "[yellow]Warning:[/yellow] Catalog entry 'extra_files' is not a mapping; "
- "additional package files will not be downloaded."
- )
- extra_files = {}
-
- def _is_required_package_file(rel_path: object) -> bool:
- """Match portable path/case aliases of the two required package files."""
- if not isinstance(rel_path, str):
- return False
- parts = PurePosixPath(rel_path.replace("\\", "/")).parts
- return len(parts) == 1 and parts[0].casefold() in {
- "step.yml",
- "__init__.py",
- }
-
- declared_extra_count = sum(
- 1
- for rel_path in (extra_files or {})
- if not _is_required_package_file(rel_path)
- )
- package_file_count = 2 + declared_extra_count
- if package_file_count > _MAX_STEP_PACKAGE_FILES:
- console.print(
- f"[red]Error:[/red] Step package declares {package_file_count} files, "
- f"exceeding the {_MAX_STEP_PACKAGE_FILES}-file limit"
- )
- raise typer.Exit(1)
-
- from specify_cli.authentication.http import open_url as _open_url
-
- def _safe_fetch(url: str) -> bytes:
- if not is_https_or_localhost_http(url):
- raise ValueError(f"Refusing to fetch from non-HTTPS URL: {url}")
- with _open_url(
- url, timeout=30, redirect_validator=_reject_insecure_download_redirect
- ) as resp:
- final_url = resp.geturl()
- if not is_https_or_localhost_http(final_url):
- raise ValueError(f"Redirect to non-HTTPS URL: {final_url}")
- return _read_response_within_limit(resp)
-
- _validate_step_id_or_exit(step_id)
-
- steps_base_dir = _resolve_steps_base_dir_or_exit(project_root)
- step_dir = (steps_base_dir / step_id).resolve()
- # Defense-in-depth: ensure the resolved directory is a direct child of
- # steps_base_dir even after symlink resolution.
- try:
- rel_parts = step_dir.relative_to(steps_base_dir).parts
- except ValueError:
- console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
- raise typer.Exit(1)
- if rel_parts != (step_id,):
- console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
- raise typer.Exit(1)
-
- import shutil
- import tempfile
-
- # Refuse if step_dir already exists (e.g. leftover from a previous failed/manual
- # install that wasn't registered). The user should remove it before retrying.
- if step_dir.exists():
- console.print(
- f"[red]Error:[/red] Step directory already exists at '{step_dir}'. "
- f"Remove it manually or use: [cyan]specify workflow step remove {step_id}[/cyan]"
- )
- raise typer.Exit(1)
-
- # Create steps_base_dir now so the staging temp dir is on the same filesystem,
- # enabling a truly atomic os.rename() below.
- try:
- steps_base_dir.mkdir(parents=True, exist_ok=True)
- tmp_path = Path(tempfile.mkdtemp(prefix="speckit_step_tmp_", dir=steps_base_dir))
- except OSError as exc:
- console.print(f"[red]Error:[/red] Failed to create staging directory: {exc}")
- raise typer.Exit(1)
- try:
- try:
- step_yml_content = _safe_fetch(step_yml_url)
- init_py_content = _safe_fetch(init_url)
- except Exception as exc:
- console.print(f"[red]Error:[/red] Failed to download step files: {exc}")
- raise typer.Exit(1)
-
- package_bytes = len(step_yml_content) + len(init_py_content)
- if package_bytes > _MAX_STEP_PACKAGE_BYTES:
- console.print(
- f"[red]Error:[/red] Step package exceeds the "
- f"{_MAX_STEP_PACKAGE_BYTES}-byte total size limit"
- )
- raise typer.Exit(1)
-
- # Validate step.yml
- try:
- import yaml as _yaml
-
- step_yml_text = step_yml_content.decode("utf-8")
- # ``safe_load`` returns None for BOTH an empty document and an
- # explicit null scalar (``null``, ``~``, ``NULL``), so it cannot
- # tell them apart on its own. ``compose`` yields no node only for
- # a genuinely empty document.
- node = _yaml.compose(step_yml_text)
- meta = _yaml.safe_load(step_yml_text)
- is_empty_document = node is None or (
- meta is None
- and isinstance(node, _yaml.nodes.ScalarNode)
- and node.value == ""
- and node.start_mark.index == node.end_mark.index
- )
- except Exception as exc:
- console.print(f"[red]Error:[/red] Invalid step.yml: {exc}")
- raise typer.Exit(1)
-
- # Do NOT coerce with ``or {}`` here: that also turns a FALSY non-mapping
- # (top-level ``[]``, ``false``, ``0``, ``''``, or an explicit ``null``)
- # into ``{}`` and silently bypasses this shape check, surfacing the
- # unrelated "missing 'step.type_key'" error below instead of the real
- # problem. Only a genuinely empty document defaults to ``{}``.
- if meta is None and is_empty_document:
- meta = {}
- elif not isinstance(meta, dict):
- console.print("[red]Error:[/red] step.yml must be a YAML mapping")
- raise typer.Exit(1)
-
- step_meta = meta.get("step", {})
- if not isinstance(step_meta, dict):
- console.print("[red]Error:[/red] step.yml 'step' field must be a mapping")
- raise typer.Exit(1)
- type_key = step_meta.get("type_key", "")
- if not type_key:
- console.print("[red]Error:[/red] step.yml missing 'step.type_key' field")
- raise typer.Exit(1)
+ _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)
- if type_key != step_id:
+ # 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:
+ if not versions_match(definition.version, expected_version):
+ _safe_discard_staged_workflow_file(staged_file, workflow_dir, existed_before)
console.print(
- f"[red]Error:[/red] step.yml type_key ({type_key!r}) does not match "
- f"catalog ID ({step_id!r})"
+ 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)
- # Write the two required files.
- try:
- (tmp_path / "step.yml").write_bytes(step_yml_content)
- (tmp_path / "__init__.py").write_bytes(init_py_content)
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to write step files to staging directory: {exc}"
+ try:
+ transaction = _workflow_install_transaction(project_root)
+ with transaction:
+ transaction_existed_before = (
+ existed_before or workflow_file.exists()
)
- raise typer.Exit(1)
-
- # Optionally download additional package files declared in the catalog entry
- # (e.g. helper modules). Each entry in ``extra_files`` is a mapping of
- # relative-path → URL. step.yml and __init__.py are ignored here (already
- # written). Paths are validated to stay within the step package directory to
- # prevent path-traversal attacks.
- for rel_path, file_url in (extra_files or {}).items():
- if not isinstance(rel_path, str) or not rel_path.strip():
- console.print(
- "[red]Error:[/red] Catalog entry 'extra_files' contains an "
- "empty or non-string path key"
- )
- raise typer.Exit(1)
- if _is_required_package_file(rel_path):
- continue # already written above
- # Reject dot-path segments ('', '.', '..') that would refer to the
- # package directory itself (IsADirectoryError) or escape it.
- rel_parts = Path(rel_path).parts
- if not rel_parts or any(seg in ("", ".", "..") for seg in rel_parts):
- console.print(
- f"[red]Error:[/red] extra_files path '{rel_path}' is not a "
- "valid relative file path"
- )
- raise typer.Exit(1)
- if not isinstance(file_url, str) or not file_url.strip():
- console.print(
- f"[red]Error:[/red] extra_files entry '{rel_path}' has an "
- "empty or non-string URL"
- )
- raise typer.Exit(1)
- # Resolve both destination and base to handle any symlinks in tmp_path itself,
- # ensuring the traversal check is robust even on non-canonical paths.
- resolved_base = tmp_path.resolve()
- dest = (tmp_path / rel_path).resolve()
+ 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 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:
- dest.relative_to(resolved_base)
- except ValueError:
- console.print(
- f"[red]Error:[/red] extra_files path '{rel_path}' is outside "
- "the step package directory"
+ backup_file = _commit_workflow_file(
+ staged_file, workflow_file, transaction_existed_before
)
- raise typer.Exit(1)
- try:
- file_content = _safe_fetch(file_url)
- except Exception as exc:
- console.print(
- f"[red]Error:[/red] Failed to download extra file '{rel_path}': {exc}"
+ except OSError as exc:
+ _safe_discard_staged_workflow_file(
+ staged_file, workflow_dir, existed_before
)
- raise typer.Exit(1)
- package_bytes += len(file_content)
- if package_bytes > _MAX_STEP_PACKAGE_BYTES:
console.print(
- f"[red]Error:[/red] Step package exceeds the "
- f"{_MAX_STEP_PACKAGE_BYTES}-byte total size limit"
+ 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:
- dest.parent.mkdir(parents=True, exist_ok=True)
- dest.write_bytes(file_content)
- except OSError as exc:
+ 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 write extra file '{rel_path}': {exc}"
+ f"[red]Error:[/red] Failed to update workflow registry for "
+ f"'{_escape_markup(workflow_id)}': "
+ f"{_escape_markup(str(exc))}"
)
raise typer.Exit(1)
-
- # Atomically rename the staging directory to the final location.
- # Both paths are under steps_base_dir (same filesystem), so os.rename()
- # is atomic on POSIX and won't leave a partially-written directory at
- # step_dir on failure.
- try:
- os.rename(tmp_path, step_dir)
- except OSError as exc:
- console.print(f"[red]Error:[/red] Failed to install step '{step_id}': {exc}")
- raise typer.Exit(1)
- finally:
- # Clean up if the rename hasn't moved tmp_path yet (i.e. on any failure).
- shutil.rmtree(tmp_path, ignore_errors=True)
-
- step_name = info.get("name") or step_id
- step_version = info.get("version") or step_meta.get("version") or "0.0.0"
-
- # Register in step registry
- registry = StepRegistry(project_root)
- try:
- registry.add(
- step_id,
- {
- "name": step_name,
- "version": step_version,
- "description": info.get("description", step_meta.get("description", "")),
- "author": info.get("author", step_meta.get("author", "")),
- "source": "catalog",
- "catalog_name": info.get("_catalog_name", ""),
- "type_key": type_key,
- },
+ # 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))}"
)
- except StepValidationError as exc:
- # Roll back the just-installed directory so the system isn't left with
- # an unregistered step package on disk after a registry write failure
- # (e.g. read-only filesystem, permission denied).
- shutil.rmtree(step_dir, ignore_errors=True)
- console.print(f"[red]Error:[/red] {exc}")
raise typer.Exit(1)
-
- console.print(
- f"[green]✓[/green] Step type '{step_name}' ({step_id}) installed"
- )
console.print(
- " Use [cyan]specify workflow step list[/cyan] to verify the installation."
+ f"[green]✓[/green] Workflow '{_escape_markup(str(info.get('name', workflow_id)))}' "
+ "installed from catalog"
)
-@workflow_step_app.command("remove")
-def workflow_step_remove(
- step_id: str = typer.Argument(..., help="Step type ID to uninstall"),
-):
- """Uninstall a custom step type."""
- from .catalog import StepRegistry, StepValidationError
-
+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()
-
- _validate_step_id_or_exit(step_id)
-
- registry = StepRegistry(project_root)
- in_registry = registry.is_installed(step_id)
-
- steps_base_dir = _resolve_steps_base_dir_or_exit(project_root)
- step_dir = (steps_base_dir / step_id).resolve()
- # Defense-in-depth: even though _validate_step_id_or_exit rejects path
- # separators, ensure that the resolved directory is a single child of
- # steps_base_dir and is not steps_base_dir itself.
+ safe_id = _escape_markup(workflow_id)
try:
- rel_parts = step_dir.relative_to(steps_base_dir).parts
- except ValueError:
- console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
- raise typer.Exit(1)
- if rel_parts != (step_id,):
- console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
- raise typer.Exit(1)
-
- dir_exists = step_dir.exists()
-
- if not in_registry and not dir_exists:
- console.print(f"[red]Error:[/red] Step type '{step_id}' is not installed")
- raise typer.Exit(1)
-
- if not in_registry and dir_exists:
- # The registry was likely reset due to corruption. Warn the user that the
- # directory is being removed even though there is no registry entry, so
- # the orphaned package can be cleaned up and a fresh install attempted.
- console.print(
- f"[yellow]Warning:[/yellow] '{step_id}' has no registry entry "
- "(registry may have been reset). Removing the orphaned directory."
- )
-
- if dir_exists and not in_registry:
- # No registry write needed; just delete the orphaned directory.
- import shutil
- try:
- shutil.rmtree(step_dir)
- except OSError as exc:
- console.print(
- f"[red]Error:[/red] Failed to remove step directory {step_dir}: {exc}"
- )
- raise typer.Exit(1)
- elif in_registry:
- # Remove the registry entry, then the directory. If the directory
- # delete fails, restore the registry entry so state stays consistent
- # and a future `step add` isn't blocked by an orphaned directory
- # with no registry entry.
- registry_metadata = registry.get(step_id)
- try:
- registry.remove(step_id)
- except StepValidationError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
- if dir_exists:
- import shutil
+ 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:
- shutil.rmtree(step_dir)
+ registry.add(workflow_id, {**metadata, "enabled": enabled})
except OSError as exc:
- # Restore the original registry entry verbatim (bypass add()
- # which would overwrite timestamps).
- try:
- if registry_metadata is not None:
- registry.data["steps"][step_id] = registry_metadata
- registry.save()
- except Exception as restore_exc: # noqa: BLE001
- console.print(
- f"[yellow]Warning:[/yellow] Failed to restore registry entry "
- f"for '{step_id}' after directory removal failure: {restore_exc}"
- )
console.print(
- f"[red]Error:[/red] Failed to remove step directory {step_dir}: {exc}"
+ f"[red]Error:[/red] Failed to update workflow registry "
+ f"for '{safe_id}': {_escape_markup(str(exc))}"
)
raise typer.Exit(1)
- console.print(f"[green]✓[/green] Step type '{step_id}' uninstalled")
-
-
-@workflow_step_app.command("search")
-def workflow_step_search(
- query: str | None = typer.Argument(None, help="Search query"),
-):
- """Search the step type catalog."""
- from .catalog import StepCatalog, StepCatalogError
-
- project_root = _require_specify_project()
-
- catalog = StepCatalog(project_root)
-
- try:
- results = catalog.search(query=query)
- except StepCatalogError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- if not results:
- if query:
- console.print(f"[yellow]No step types found matching '{query}'.[/yellow]")
- else:
- console.print("[yellow]No step types found in catalog.[/yellow]")
- return
-
- console.print(f"\n[bold cyan]Step Types ({len(results)}):[/bold cyan]\n")
- for step in results:
- install_note = (
- "" if step.get("_install_allowed", True) else " [dim](discovery only)[/dim]"
- )
- name = _escape_markup(str(step.get("name", step.get("id", "?"))))
- step_id = _escape_markup(str(step.get("id", "?")))
- version = _escape_markup(str(step.get("version", "?")))
- console.print(
- f" [bold]{name}[/bold] ({step_id}) v{version}{install_note}"
- )
- desc = step.get("description", "")
- if desc:
- console.print(f" {_escape_markup(str(desc))}")
- console.print()
-
-
-@workflow_step_app.command("info")
-def workflow_step_info(
- step_id: str = typer.Argument(..., help="Step type ID"),
-):
- """Show details for a step type."""
- from . import STEP_REGISTRY
- from .catalog import StepCatalog, StepCatalogError, StepRegistry
-
- project_root = _require_specify_project()
- safe_step_id = _escape_markup(str(step_id))
-
- registry = StepRegistry(project_root)
- installed_meta = registry.get(step_id)
-
- # Check if it's a built-in
- builtin_step = STEP_REGISTRY.get(step_id)
- is_builtin = builtin_step is not None and not installed_meta
-
- if is_builtin:
- console.print(f"\n[bold cyan]{safe_step_id}[/bold cyan] [dim](built-in)[/dim]")
- console.print(f" Type key: {safe_step_id}")
- console.print(" [green]Built-in step type[/green]")
- return
-
- if installed_meta:
- name = _escape_markup(str(installed_meta.get("name", step_id)))
- version = _escape_markup(str(installed_meta.get("version", "?")))
- console.print(
- f"\n[bold cyan]{name}[/bold cyan] ({safe_step_id})"
- )
- console.print(f" Version: {version}")
- if installed_meta.get("author"):
- console.print(
- f" Author: {_escape_markup(str(installed_meta['author']))}"
- )
- if installed_meta.get("description"):
- console.print(
- f" Description: "
- f"{_escape_markup(str(installed_meta['description']))}"
- )
- console.print(" [green]Installed[/green]")
- return
-
- # Try catalog
- catalog = StepCatalog(project_root)
- try:
- info = catalog.get_step_info(step_id)
- except StepCatalogError:
- info = None
-
- if info:
- name = _escape_markup(str(info.get("name", step_id)))
- version = _escape_markup(str(info.get("version", "?")))
- console.print(
- f"\n[bold cyan]{name}[/bold cyan] ({safe_step_id})"
- )
- console.print(f" Version: {version}")
- if info.get("author"):
- console.print(f" Author: {_escape_markup(str(info['author']))}")
- if info.get("description"):
- console.print(
- f" Description: {_escape_markup(str(info['description']))}"
- )
- console.print(" [yellow]Not installed[/yellow]")
+ except OSError as exc:
console.print(
- f"\n Install with: [cyan]specify workflow step add {safe_step_id}[/cyan]"
- )
- else:
- console.print(f"[red]Error:[/red] Step type '{safe_step_id}' not found")
- raise typer.Exit(1)
-
-
-@workflow_step_catalog_app.command("list")
-def workflow_step_catalog_list():
- """List configured step catalog sources."""
- from .catalog import StepCatalog, StepCatalogError
-
- project_root = _require_specify_project()
- catalog = StepCatalog(project_root)
-
- try:
- configs = catalog.get_catalog_configs()
- except StepCatalogError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- console.print("\n[bold cyan]Step Catalog Sources:[/bold cyan]\n")
- for i, cfg in enumerate(configs):
- install_status = (
- "[green]install allowed[/green]"
- if cfg["install_allowed"]
- else "[yellow]discovery only[/yellow]"
+ f"[red]Error:[/red] Failed to lock workflow registry for "
+ f"'{safe_id}': {_escape_markup(str(exc))}"
)
- console.print(f" [{i}] [bold]{_escape_markup(str(cfg['name']))}[/bold] — {install_status}")
- console.print(f" {_escape_markup(str(cfg['url']))}")
- if cfg.get("description"):
- console.print(f" [dim]{_escape_markup(str(cfg['description']))}[/dim]")
- console.print()
-
-
-@workflow_step_catalog_app.command("add")
-def workflow_step_catalog_add(
- url: str = typer.Argument(..., help="Catalog URL to add"),
- name: str | None = typer.Option(None, "--name", help="Catalog name"),
-):
- """Add a step catalog source."""
- from .catalog import StepCatalog, StepValidationError
-
- project_root = _require_specify_project()
-
- catalog = StepCatalog(project_root)
- try:
- catalog.add_catalog(url, name)
- except StepValidationError as exc:
- console.print(f"[red]Error:[/red] {exc}")
- raise typer.Exit(1)
-
- console.print(f"[green]✓[/green] Step catalog source added: {url}")
-
-
-@workflow_step_catalog_app.command("remove")
-def workflow_step_catalog_remove(
- index: int = typer.Argument(
- ..., help="Catalog index to remove (from 'step catalog list')"
- ),
-):
- """Remove a step catalog source by index."""
- from .catalog import StepCatalog, StepValidationError
-
- project_root = _require_specify_project()
-
- catalog = StepCatalog(project_root)
- try:
- removed_name = catalog.remove_catalog(index)
- except StepValidationError as exc:
- console.print(f"[red]Error:[/red] {exc}")
raise typer.Exit(1)
-
- console.print(f"[green]✓[/green] Step catalog source '{removed_name}' removed")
+ state = "enabled" if enabled else "disabled"
+ console.print(f"[green]✓[/green] Workflow '{safe_id}' {state}")
-@workflow_overlay_app.command("add")
-def workflow_overlay_add_cmd(
- source: Path = typer.Argument(..., help="Path to overlay YAML file"),
- priority: int = typer.Option(
- 10,
- "--priority",
- help="Resolution priority (lower = higher precedence, default 10)",
- ),
-):
- """Add a project-local overlay for a workflow."""
- from .overlays._commands import workflow_overlay_add
+# Compatibility forwarders for established public and direct-call paths.
+def workflow_add(*args, **kwargs):
+ from .command_add import workflow_add as command
- project_root = _require_specify_project()
- if workflow_overlay_add(project_root, source, priority) is None:
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_overlay_app.command("set-priority")
-def workflow_overlay_set_priority_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),
- overlay_id: str = typer.Argument(..., help="Overlay ID"),
- priority: int = typer.Argument(
- ..., help="New priority (lower = higher precedence)"
- ),
-):
- """Set the priority of a project-local overlay."""
- from .overlays._commands import workflow_overlay_set_priority
+def workflow_remove(*args, **kwargs):
+ from .command_remove import workflow_remove as command
- project_root = _require_specify_project()
- if not workflow_overlay_set_priority(project_root, workflow_id, overlay_id, priority):
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_overlay_app.command("enable")
-def workflow_overlay_enable_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),
- overlay_id: str = typer.Argument(..., help="Overlay ID"),
-):
- """Enable a project-local overlay."""
- from .overlays._commands import workflow_overlay_enable
+def workflow_status(*args, **kwargs):
+ from .command_status import workflow_status as command
- project_root = _require_specify_project()
- if not workflow_overlay_enable(project_root, workflow_id, overlay_id):
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_overlay_app.command("disable")
-def workflow_overlay_disable_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),
- overlay_id: str = typer.Argument(..., help="Overlay ID"),
-):
- """Disable a project-local overlay."""
- from .overlays._commands import workflow_overlay_disable
+def workflow_enable(*args, **kwargs):
+ from .command_enable import workflow_enable as command
- project_root = _require_specify_project()
- if not workflow_overlay_disable(project_root, workflow_id, overlay_id):
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_overlay_app.command("remove")
-def workflow_overlay_remove_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),
- overlay_id: str = typer.Argument(..., help="Overlay ID"),
-):
- """Remove a project-local overlay."""
- from .overlays._commands import workflow_overlay_remove
+def workflow_disable(*args, **kwargs):
+ from .command_disable import workflow_disable as command
- project_root = _require_specify_project()
- if not workflow_overlay_remove(project_root, workflow_id, overlay_id):
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_overlay_app.command("list")
-def workflow_overlay_list_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID"),
-):
- """List overlays for a workflow."""
- from .overlays._commands import workflow_overlay_list
+def workflow_step_add(*args, **kwargs):
+ from .step.command_add import workflow_step_add as command
- project_root = _require_specify_project()
- if workflow_overlay_list(project_root, workflow_id) is None:
- raise typer.Exit(1)
+ return command(*args, **kwargs)
-@workflow_app.command("resolve")
-def workflow_resolve_cmd(
- workflow_id: str = typer.Argument(..., help="Workflow ID to resolve"),
-):
- """Show layer attribution for a resolved workflow."""
- from .overlays._commands import workflow_resolve
+def workflow_step_remove(*args, **kwargs):
+ from .step.command_remove import workflow_step_remove as command
- project_root = _require_specify_project()
- if workflow_resolve(project_root, workflow_id) is None:
- raise typer.Exit(1)
+ 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")
diff --git a/src/specify_cli/workflows/catalog/__init__.py b/src/specify_cli/workflows/catalog/__init__.py
new file mode 100644
index 000000000..0e2667558
--- /dev/null
+++ b/src/specify_cli/workflows/catalog/__init__.py
@@ -0,0 +1,60 @@
+"""Workflow catalog domain API and nested CLI registration."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+import typer
+
+from ..._download_security import MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES
+
+catalog_app = typer.Typer(
+ name="catalog",
+ help="Manage workflow catalogs",
+ add_completion=False,
+)
+
+
+def register(app: typer.Typer) -> None:
+ """Attach the workflow catalog group to the workflow app."""
+ from . import command_list # noqa: F401 -- registers handler
+ from . import command_add # noqa: F401 -- registers handler
+ from . import command_remove # noqa: F401 -- registers handler
+
+ app.add_typer(catalog_app, name="catalog")
+
+
+_DOMAIN_EXPORTS = {
+ "WorkflowCatalog",
+ "WorkflowCatalogEntry",
+ "WorkflowCatalogError",
+ "WorkflowRegistry",
+ "WorkflowValidationError",
+}
+_STEP_COMPATIBILITY_EXPORTS = {
+ "StepCatalog",
+ "StepCatalogEntry",
+ "StepCatalogError",
+ "StepRegistry",
+ "StepValidationError",
+}
+_COMPATIBILITY_EXPORTS = {"json", "os", "tempfile"}
+
+
+def __getattr__(name: str) -> Any:
+ """Load catalog domain symbols only when a consumer requests them."""
+ if name in _STEP_COMPATIBILITY_EXPORTS:
+ step_catalog = import_module("..step.catalog", __name__)
+ value = getattr(step_catalog, name)
+ globals()[name] = value
+ return value
+ if name not in _DOMAIN_EXPORTS | _COMPATIBILITY_EXPORTS:
+ raise AttributeError(name)
+ domain = import_module(f"{__name__}._domain")
+ value = getattr(domain, name)
+ globals()[name] = value
+ return value
+
+
+__all__ = sorted(_DOMAIN_EXPORTS | _STEP_COMPATIBILITY_EXPORTS)
diff --git a/src/specify_cli/workflows/catalog.py b/src/specify_cli/workflows/catalog/_domain.py
similarity index 54%
rename from src/specify_cli/workflows/catalog.py
rename to src/specify_cli/workflows/catalog/_domain.py
index 5fffa4b45..089b46f2a 100644
--- a/src/specify_cli/workflows/catalog.py
+++ b/src/specify_cli/workflows/catalog/_domain.py
@@ -1,10 +1,9 @@
-"""Workflow catalog — discovery, install, and management of workflows and step types.
+"""Workflow catalog discovery, installation, and registry domain API.
Mirrors the existing extension/preset catalog pattern with:
- Multi-catalog stack (env var → project → user → built-in)
- SHA256-hashed per-URL caching with 1-hour TTL
- Workflow registry for installed workflow tracking
-- Step registry for installed custom step type tracking
- Search across all configured catalog sources
"""
@@ -22,7 +21,17 @@ from typing import Any
import yaml
-from .._download_security import MAX_JSON_CATALOG_BYTES, read_response_limited
+from ..._download_security import (
+ MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES,
+ read_response_limited,
+)
+
+
+def _max_json_catalog_bytes() -> int:
+ """Read the compatibility-exposed size limit at call time."""
+ from . import MAX_JSON_CATALOG_BYTES as configured_limit
+
+ return configured_limit
# ---------------------------------------------------------------------------
@@ -568,7 +577,7 @@ class WorkflowCatalog:
data = json.loads(
read_response_limited(
resp,
- max_bytes=MAX_JSON_CATALOG_BYTES,
+ max_bytes=_max_json_catalog_bytes(),
error_type=WorkflowCatalogError,
label="workflow catalog",
).decode("utf-8")
@@ -820,688 +829,3 @@ class WorkflowCatalog:
if isinstance(removed, dict):
return removed.get("name", f"catalog-{index + 1}")
return f"catalog-{index + 1}"
-
-
-# ---------------------------------------------------------------------------
-# Step catalog errors
-# ---------------------------------------------------------------------------
-
-
-class StepCatalogError(Exception):
- """Base error for step catalog operations."""
-
-
-class StepValidationError(StepCatalogError):
- """Validation error for step catalog config or step data."""
-
-
-# ---------------------------------------------------------------------------
-# StepCatalogEntry
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class StepCatalogEntry:
- """Represents a single step catalog source in the catalog stack."""
-
- url: str
- name: str
- priority: int
- install_allowed: bool
- description: str = ""
-
-
-# ---------------------------------------------------------------------------
-# StepRegistry
-# ---------------------------------------------------------------------------
-
-
-class StepRegistry:
- """Manages the registry of installed custom step types.
-
- Tracks installed step types and their metadata in
- ``.specify/workflows/steps/step-registry.json``.
- """
-
- REGISTRY_FILE = "step-registry.json"
- SCHEMA_VERSION = "1.0"
-
- def __init__(self, project_root: Path) -> None:
- self.project_root = project_root
- self.steps_dir = project_root / ".specify" / "workflows" / "steps"
- self.registry_path = self.steps_dir / self.REGISTRY_FILE
- self.data = self._load()
-
- def _has_symlinked_parent(self) -> bool:
- """Return True if any directory under .specify/workflows/steps is a symlink."""
- current = self.project_root
- for part in (".specify", "workflows", "steps"):
- current = current / part
- if current.is_symlink():
- return True
- return False
-
- def _load(self) -> dict[str, Any]:
- """Load registry from disk or create default."""
- default_registry: dict[str, Any] = {"schema_version": self.SCHEMA_VERSION, "steps": {}}
- # Defense-in-depth: refuse to read the registry if any parent directory
- # under .specify/workflows/steps is a symlink, which could redirect the
- # read outside the project root.
- if self._has_symlinked_parent():
- return default_registry
- # Defense-in-depth: also refuse to read a symlinked registry file,
- # which could redirect the read outside the project root.
- if self.registry_path.is_symlink():
- return default_registry
- if self.registry_path.exists():
- try:
- with open(self.registry_path, encoding="utf-8") as f:
- data = json.load(f)
- # Validate shape: must be a dict with a dict "steps" field
- if not isinstance(data, dict):
- return default_registry
- if not isinstance(data.get("steps"), dict):
- data["steps"] = {}
- return data
- except (json.JSONDecodeError, ValueError, OSError, UnicodeError):
- return default_registry
- return default_registry
-
- def save(self) -> None:
- """Persist registry to disk.
-
- Raises ``StepValidationError`` with a clear message on filesystem
- errors (read-only fs, permission denied, ...) so callers can surface
- a clean error to the user rather than an unhandled ``OSError``.
- """
- if self._has_symlinked_parent() or self.registry_path.is_symlink():
- raise StepValidationError(
- "Refusing to write step registry through a symlinked path."
- )
- try:
- self.steps_dir.mkdir(parents=True, exist_ok=True)
- with open(self.registry_path, "w", encoding="utf-8") as f:
- json.dump(self.data, f, indent=2)
- except OSError as exc:
- raise StepValidationError(
- f"Failed to write step registry at {self.registry_path}: {exc}"
- ) from exc
-
- def add(self, step_id: str, metadata: dict[str, Any]) -> None:
- """Add or update an installed step entry."""
- import copy
- from datetime import datetime, timezone
-
- raw_existing = self.data["steps"].get(step_id)
- # Corrupted-but-parseable registries may hold non-dict entries; treat
- # them as absent rather than crashing on existing.get() (mirrors
- # WorkflowRegistry.add).
- existing = raw_existing if isinstance(raw_existing, dict) else {}
- metadata_to_store = copy.deepcopy(metadata)
- metadata_to_store["installed_at"] = existing.get(
- "installed_at", datetime.now(timezone.utc).isoformat()
- )
- metadata_to_store["updated_at"] = datetime.now(timezone.utc).isoformat()
- self.data["steps"][step_id] = metadata_to_store
- self.save()
-
- def remove(self, step_id: str) -> bool:
- """Remove an installed step entry. Returns True if found."""
- if step_id in self.data["steps"]:
- del self.data["steps"][step_id]
- self.save()
- return True
- return False
-
- def get(self, step_id: str) -> dict[str, Any] | None:
- """Get metadata for an installed step."""
- return self.data["steps"].get(step_id)
-
- def list(self) -> dict[str, dict[str, Any]]:
- """Return all installed steps."""
- return dict(self.data["steps"])
-
- def is_installed(self, step_id: str) -> bool:
- """Check if a step is installed."""
- return step_id in self.data["steps"]
-
-
-# ---------------------------------------------------------------------------
-# StepCatalog
-# ---------------------------------------------------------------------------
-
-
-class StepCatalog:
- """Manages step catalog fetching, caching, and searching.
-
- Resolution order for catalog sources:
- 1. ``SPECKIT_STEP_CATALOG_URL`` env var (overrides all)
- 2. Project-level ``.specify/step-catalogs.yml``
- 3. User-level ``~/.specify/step-catalogs.yml``
- 4. Built-in defaults (official + community)
- """
-
- DEFAULT_CATALOG_URL = (
- "https://raw.githubusercontent.com/github/spec-kit/main/"
- "workflows/step-catalog.json"
- )
- COMMUNITY_CATALOG_URL = (
- "https://raw.githubusercontent.com/github/spec-kit/main/"
- "workflows/step-catalog.community.json"
- )
- CACHE_DURATION = 3600 # 1 hour
-
- def __init__(self, project_root: Path) -> None:
- self.project_root = project_root
- self.steps_dir = project_root / ".specify" / "workflows" / "steps"
- self.cache_dir = self.steps_dir / ".cache"
-
- def _is_cache_path_safe(self) -> bool:
- """Return False if any component of the cache path is a symlink."""
- current = self.project_root
- for part in (".specify", "workflows", "steps", ".cache"):
- current = current / part
- if current.is_symlink():
- return False
- return True
-
- # -- Catalog resolution -----------------------------------------------
-
- def _validate_catalog_url(self, url: str) -> None:
- """Validate that a catalog URL uses HTTPS (localhost HTTP allowed)."""
- from urllib.parse import urlparse
-
- # A malformed authority (e.g. an unterminated IPv6 bracket
- # "https://[::1") makes urlparse / hostname access raise ValueError.
- # This validator's contract is to raise StepValidationError for a bad
- # URL, so surface that rather than leaking a raw ValueError past the
- # command handler (which only catches StepValidationError). Mirrors
- # specify_cli.catalogs (#3435).
- try:
- parsed = urlparse(url)
- hostname = parsed.hostname
- _ = parsed.port
- except (TypeError, ValueError):
- raise StepValidationError(
- f"Catalog URL is malformed: {url}"
- ) from None
- is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
- if parsed.scheme != "https" and not (
- parsed.scheme == "http" and is_localhost
- ):
- raise StepValidationError(
- f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
- "HTTP is only allowed for localhost."
- )
- if not hostname:
- raise StepValidationError(
- "Catalog URL must be a valid URL with a host."
- )
-
- def _load_catalog_config(
- self, config_path: Path
- ) -> list[StepCatalogEntry] | None:
- """Load catalog stack configuration from a YAML file."""
- if not config_path.exists():
- return None
- try:
- data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
- except (yaml.YAMLError, OSError, UnicodeError) as exc:
- raise StepValidationError(
- f"Failed to read catalog config {config_path}: {exc}"
- ) from exc
- # Same two guards as WorkflowCatalog._load_catalog_config above, kept in
- # lockstep: this is the step-catalog twin of that loader and read the
- # same way. Dropping ``or {}`` stops a falsy non-mapping top level from
- # being coerced past the isinstance check, and the ``catalogs`` shape
- # check runs before the emptiness check for the same reason.
- if data is None:
- return None
- if not isinstance(data, dict):
- raise StepValidationError(
- f"Invalid catalog config: expected a mapping, "
- f"got {type(data).__name__}"
- )
- catalogs_data = data.get("catalogs")
- if catalogs_data is None:
- return None
- if not isinstance(catalogs_data, list):
- raise StepValidationError(
- f"Invalid catalog config: 'catalogs' must be a list, "
- f"got {type(catalogs_data).__name__}"
- )
- if not catalogs_data:
- return None
-
- entries: list[StepCatalogEntry] = []
- for idx, item in enumerate(catalogs_data):
- if not isinstance(item, dict):
- raise StepValidationError(
- f"Invalid catalog entry at index {idx}: "
- f"expected a mapping, got {type(item).__name__}"
- )
- url = str(item.get("url", "")).strip()
- if not url:
- continue
- self._validate_catalog_url(url)
- raw_priority = item.get("priority", idx + 1)
- # bool is an int subclass: reject ``priority: true`` explicitly rather
- # than silently coercing it to 1 (mirrors CatalogStackBase).
- if isinstance(raw_priority, bool):
- raise StepValidationError(
- f"Invalid priority for catalog "
- f"'{item.get('name', idx + 1)}': "
- f"expected integer, got {raw_priority!r}"
- )
- try:
- priority = int(raw_priority)
- except (TypeError, ValueError, OverflowError):
- # OverflowError: int(float("inf")) — a ``priority: .inf``.
- raise StepValidationError(
- f"Invalid priority for catalog "
- f"'{item.get('name', idx + 1)}': "
- f"expected integer, got {raw_priority!r}"
- )
- raw_install = item.get("install_allowed", False)
- if isinstance(raw_install, str):
- install_allowed = raw_install.strip().lower() in (
- "true",
- "yes",
- "1",
- )
- else:
- install_allowed = bool(raw_install)
- entries.append(
- StepCatalogEntry(
- url=url,
- name=str(item.get("name", f"catalog-{idx + 1}")),
- priority=priority,
- install_allowed=install_allowed,
- description=str(item.get("description", "")),
- )
- )
- entries.sort(key=lambda e: e.priority)
- if not entries:
- raise StepValidationError(
- f"Catalog config {config_path} contains {len(catalogs_data)} "
- f"entries but none have valid URLs."
- )
- return entries
-
- def get_active_catalogs(self) -> list[StepCatalogEntry]:
- """Get the ordered list of active step catalogs."""
- # 1. Environment variable override
- env_url = os.environ.get("SPECKIT_STEP_CATALOG_URL", "").strip()
- if env_url:
- self._validate_catalog_url(env_url)
- return [
- StepCatalogEntry(
- url=env_url,
- name="env-override",
- priority=1,
- install_allowed=True,
- description="From SPECKIT_STEP_CATALOG_URL",
- )
- ]
-
- # 2. Project-level config
- project_config = self.project_root / ".specify" / "step-catalogs.yml"
- project_entries = self._load_catalog_config(project_config)
- if project_entries is not None:
- return project_entries
-
- # 3. User-level config
- home = Path.home()
- user_config = home / ".specify" / "step-catalogs.yml"
- user_entries = self._load_catalog_config(user_config)
- if user_entries is not None:
- return user_entries
-
- # 4. Built-in defaults
- return [
- StepCatalogEntry(
- url=self.DEFAULT_CATALOG_URL,
- name="default",
- priority=1,
- install_allowed=True,
- description="Official step types",
- ),
- StepCatalogEntry(
- url=self.COMMUNITY_CATALOG_URL,
- name="community",
- priority=2,
- install_allowed=False,
- description="Community-contributed step types (discovery only)",
- ),
- ]
-
- # -- Caching ----------------------------------------------------------
-
- def _get_cache_paths(self, url: str) -> tuple[Path, Path]:
- """Get cache file paths for a URL (hash-based)."""
- url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]
- cache_file = self.cache_dir / f"step-catalog-{url_hash}.json"
- meta_file = self.cache_dir / f"step-catalog-{url_hash}-meta.json"
- return cache_file, meta_file
-
- def _is_url_cache_valid(self, url: str) -> bool:
- """Check if cached data for a URL is still fresh."""
- _, meta_file = self._get_cache_paths(url)
- if not meta_file.exists():
- return False
- try:
- with open(meta_file, encoding="utf-8") as f:
- meta = json.load(f)
- if not isinstance(meta, dict):
- return False
- fetched_at = float(meta.get("fetched_at", 0))
- return (time.time() - fetched_at) < self.CACHE_DURATION
- except (json.JSONDecodeError, OSError, TypeError, ValueError):
- return False
-
- def _fetch_single_catalog(
- self, entry: StepCatalogEntry, force_refresh: bool = False
- ) -> dict[str, Any]:
- """Fetch a single catalog, using cache when possible."""
- cache_safe = self._is_cache_path_safe()
- cache_file, meta_file = self._get_cache_paths(entry.url)
-
- if cache_safe and not force_refresh and self._is_url_cache_valid(entry.url):
- try:
- with open(cache_file, encoding="utf-8") as f:
- cached = json.load(f)
- if isinstance(cached, dict):
- return cached
- except (UnicodeDecodeError, json.JSONDecodeError, OSError):
- # Ignore invalid/unreadable cache and fall back to fetching from source.
- pass
-
- from urllib.parse import urlparse
- from specify_cli.authentication.http import open_url as _open_url
-
- def _validate_url(url: str) -> None:
- # A malformed authority (e.g. "https://[::1") makes urlparse /
- # hostname access raise ValueError; treat it as a refused fetch
- # rather than leaking a raw ValueError (this also validates the
- # post-redirect resp.geturl(), so a hostile redirect target cannot
- # crash the fetch either).
- try:
- parsed = urlparse(url)
- hostname = parsed.hostname
- _ = parsed.port
- except (TypeError, ValueError):
- raise StepCatalogError(
- f"Refusing to fetch catalog from malformed URL: {url}"
- ) from None
- is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
- if parsed.scheme != "https" and not (
- parsed.scheme == "http" and is_localhost
- ):
- raise StepCatalogError(
- f"Refusing to fetch catalog from non-HTTPS URL: {url}"
- )
- if not hostname:
- raise StepCatalogError(
- f"Refusing to fetch catalog from URL with no hostname: {url}"
- )
-
- _validate_url(entry.url)
-
- # Validate EVERY redirect hop, not just the final URL: _open_url follows
- # redirects, so an https:// entry that 30x-redirects through http:// (or
- # to a non-HTTPS host mid-chain) could otherwise let a network attacker
- # rewrite the next hop and slip a payload past a final-URL-only check.
- # redirect_validator runs before each hop; the geturl() check below is
- # retained as a defense-in-depth backstop. Mirrors the presets/extensions
- # catalog fix (#3523 / #3524).
- def _validate_redirect(_old_url: str, new_url: str) -> None:
- _validate_url(new_url)
-
- try:
- with _open_url(
- entry.url, timeout=30, redirect_validator=_validate_redirect
- ) as resp:
- _validate_url(resp.geturl())
- data = json.loads(
- read_response_limited(
- resp,
- max_bytes=MAX_JSON_CATALOG_BYTES,
- error_type=StepCatalogError,
- label="step catalog",
- ).decode("utf-8")
- )
- except Exception as exc:
- if cache_safe and cache_file.exists():
- try:
- with open(cache_file, encoding="utf-8") as f:
- cached = json.load(f)
- if isinstance(cached, dict):
- return cached
- except (json.JSONDecodeError, ValueError, OSError):
- # Stale-cache read failed; let the original fetch error propagate.
- pass
- raise StepCatalogError(
- f"Failed to fetch catalog from {entry.url}: {exc}"
- ) from exc
-
- if not isinstance(data, dict):
- raise StepCatalogError(
- f"Catalog from {entry.url} is not a valid JSON object."
- )
-
- if cache_safe:
- try:
- self.cache_dir.mkdir(parents=True, exist_ok=True)
- with open(cache_file, "w", encoding="utf-8") as f:
- json.dump(data, f, indent=2)
- with open(meta_file, "w", encoding="utf-8") as f:
- json.dump({"url": entry.url, "fetched_at": time.time()}, f)
- except OSError:
- pass # Proceed without caching if disk write fails
-
- return data
-
- def _get_merged_steps(
- self, force_refresh: bool = False
- ) -> dict[str, dict[str, Any]]:
- """Merge steps from all active catalogs (lower priority number wins)."""
- catalogs = self.get_active_catalogs()
- merged: dict[str, dict[str, Any]] = {}
- fetch_errors = 0
-
- for entry in reversed(catalogs):
- try:
- data = self._fetch_single_catalog(entry, force_refresh)
- except StepCatalogError:
- fetch_errors += 1
- continue
- steps = data.get("steps", {})
- if isinstance(steps, dict):
- for step_id, step_data in steps.items():
- if not isinstance(step_data, dict):
- continue
- step_data["_catalog_name"] = entry.name
- step_data["_install_allowed"] = entry.install_allowed
- merged[step_id] = step_data
- elif isinstance(steps, list):
- for step_data in steps:
- if not isinstance(step_data, dict):
- continue
- raw_step_id = step_data.get("id")
- if raw_step_id is None:
- continue
- step_id = str(raw_step_id).strip()
- if step_id:
- step_data["id"] = step_id
- step_data["_catalog_name"] = entry.name
- step_data["_install_allowed"] = entry.install_allowed
- merged[step_id] = step_data
- if fetch_errors == len(catalogs) and catalogs:
- raise StepCatalogError("All configured step catalogs failed to fetch.")
- return merged
-
- # -- Public API -------------------------------------------------------
-
- def search(
- self,
- query: str | None = None,
- ) -> list[dict[str, Any]]:
- """Search step types across all configured catalogs."""
- merged = self._get_merged_steps()
- results: list[dict[str, Any]] = []
-
- for step_id, step_data in merged.items():
- step_data.setdefault("id", step_id)
- if query:
- q = query.lower()
- searchable = " ".join(
- [
- str(step_data.get("name") or ""),
- str(step_data.get("description") or ""),
- str(step_data.get("id") or ""),
- ]
- ).lower()
- if q not in searchable:
- continue
- results.append(step_data)
- return results
-
- def get_step_info(self, step_id: str) -> dict[str, Any] | None:
- """Get details for a specific step from the catalog."""
- merged = self._get_merged_steps()
- step = merged.get(step_id)
- if step:
- step.setdefault("id", step_id)
- return step
-
- def get_catalog_configs(self) -> list[dict[str, Any]]:
- """Return current catalog configuration as a list of dicts."""
- entries = self.get_active_catalogs()
- return [
- {
- "name": e.name,
- "url": e.url,
- "priority": e.priority,
- "install_allowed": e.install_allowed,
- "description": e.description,
- }
- for e in entries
- ]
-
- def add_catalog(self, url: str, name: str | None = None) -> None:
- """Add a catalog source to the project-level config."""
- self._validate_catalog_url(url)
- config_path = self.project_root / ".specify" / "step-catalogs.yml"
-
- data: dict[str, Any] = {"catalogs": []}
- if config_path.exists():
- try:
- raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
- except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
- raise StepValidationError(
- f"Catalog config file is unreadable or malformed: {exc}"
- ) from exc
- if raw is None:
- raw = {}
- elif not isinstance(raw, dict):
- raise StepValidationError(
- "Catalog config file is corrupted (expected a mapping)."
- )
- data = raw
-
- catalogs = data.get("catalogs", [])
- if not isinstance(catalogs, list):
- raise StepValidationError(
- "Catalog config 'catalogs' must be a list."
- )
- for cat in catalogs:
- if isinstance(cat, dict) and cat.get("url") == url:
- raise StepValidationError(
- f"Catalog URL already configured: {url}"
- )
-
- # Coerce existing priorities to int with a safe fallback so a user-edited
- # step-catalogs.yml with a non-integer priority (e.g. "1") doesn't blow up.
- def _coerce_priority(value: Any) -> int:
- try:
- return int(value)
- except (TypeError, ValueError, OverflowError):
- # OverflowError: int(float("inf")) — treat an uncoercible
- # existing priority as 0 rather than crashing 'catalog add'.
- return 0
-
- max_priority = max(
- (
- _coerce_priority(cat.get("priority", 0))
- for cat in catalogs
- if isinstance(cat, dict)
- ),
- default=0,
- )
- catalogs.append(
- {
- "name": name or f"catalog-{len(catalogs) + 1}",
- "url": url,
- "priority": max_priority + 1,
- "install_allowed": True,
- "description": "",
- }
- )
- data["catalogs"] = catalogs
-
- try:
- config_path.parent.mkdir(parents=True, exist_ok=True)
- with open(config_path, "w", encoding="utf-8") as f:
- yaml.dump(
- data, f, default_flow_style=False, sort_keys=False, allow_unicode=True
- )
- except OSError as exc:
- raise StepValidationError(
- f"Failed to write catalog config {config_path}: {exc}"
- ) from exc
-
- def remove_catalog(self, index: int) -> str:
- """Remove a catalog source by index (0-based). Returns the removed name."""
- config_path = self.project_root / ".specify" / "step-catalogs.yml"
- if not config_path.exists():
- raise StepValidationError("No step catalog config file found.")
-
- try:
- data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
- except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
- raise StepValidationError(
- f"Catalog config file is unreadable or malformed: {exc}"
- ) from exc
- if data is None:
- data = {}
- elif not isinstance(data, dict):
- raise StepValidationError(
- "Catalog config file is corrupted (expected a mapping)."
- )
- catalogs = data.get("catalogs", [])
- if not isinstance(catalogs, list):
- raise StepValidationError(
- "Catalog config 'catalogs' must be a list."
- )
-
- if index < 0 or index >= len(catalogs):
- raise StepValidationError(
- f"Catalog index {index} out of range (0-{len(catalogs) - 1})."
- )
-
- removed = catalogs.pop(index)
- data["catalogs"] = catalogs
-
- try:
- with open(config_path, "w", encoding="utf-8") as f:
- yaml.dump(
- data, f, default_flow_style=False, sort_keys=False, allow_unicode=True
- )
- except OSError as exc:
- raise StepValidationError(
- f"Failed to write catalog config {config_path}: {exc}"
- ) from exc
-
- if isinstance(removed, dict):
- return removed.get("name", f"catalog-{index + 1}")
- return f"catalog-{index + 1}"
diff --git a/src/specify_cli/workflows/catalog/command_add.py b/src/specify_cli/workflows/catalog/command_add.py
new file mode 100644
index 000000000..6363c07c2
--- /dev/null
+++ b/src/specify_cli/workflows/catalog/command_add.py
@@ -0,0 +1,25 @@
+"""Command handler for ``specify workflow catalog add``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("add")
+def workflow_catalog_add(
+ url: str = cli.typer.Argument(..., help="Catalog URL to add"),
+ name: str | None = cli.typer.Option(None, "--name", help="Catalog name"),
+):
+ """Add a workflow catalog source."""
+ from . import WorkflowCatalog, WorkflowValidationError
+
+ project_root = cli._require_specify_project()
+ catalog = WorkflowCatalog(project_root)
+ try:
+ catalog.add_catalog(url, name)
+ except WorkflowValidationError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Catalog source added: {url}")
diff --git a/src/specify_cli/workflows/catalog/command_list.py b/src/specify_cli/workflows/catalog/command_list.py
new file mode 100644
index 000000000..d3084739e
--- /dev/null
+++ b/src/specify_cli/workflows/catalog/command_list.py
@@ -0,0 +1,38 @@
+"""Command handler for ``specify workflow catalog list``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("list")
+def workflow_catalog_list():
+ """List configured workflow catalog sources."""
+ from . import WorkflowCatalog, WorkflowCatalogError
+
+ project_root = cli._require_specify_project()
+ catalog = WorkflowCatalog(project_root)
+
+ try:
+ configs = catalog.get_catalog_configs()
+ except WorkflowCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print("\n[bold cyan]Workflow Catalog Sources:[/bold cyan]\n")
+ for i, cfg in enumerate(configs):
+ install_status = (
+ "[green]install allowed[/green]"
+ if cfg["install_allowed"]
+ else "[yellow]discovery only[/yellow]"
+ )
+ cli.console.print(
+ f" [{i}] [bold]{cli._escape_markup(str(cfg['name']))}[/bold] — {install_status}"
+ )
+ cli.console.print(f" {cli._escape_markup(str(cfg['url']))}")
+ if cfg.get("description"):
+ cli.console.print(
+ f" [dim]{cli._escape_markup(str(cfg['description']))}[/dim]"
+ )
+ cli.console.print()
diff --git a/src/specify_cli/workflows/catalog/command_remove.py b/src/specify_cli/workflows/catalog/command_remove.py
new file mode 100644
index 000000000..4240e6cdb
--- /dev/null
+++ b/src/specify_cli/workflows/catalog/command_remove.py
@@ -0,0 +1,26 @@
+"""Command handler for ``specify workflow catalog remove``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("remove")
+def workflow_catalog_remove(
+ index: int = cli.typer.Argument(
+ ..., help="Catalog index to remove (from 'catalog list')"
+ ),
+):
+ """Remove a workflow catalog source by index."""
+ from . import WorkflowCatalog, WorkflowValidationError
+
+ project_root = cli._require_specify_project()
+ catalog = WorkflowCatalog(project_root)
+ try:
+ removed_name = catalog.remove_catalog(index)
+ except WorkflowValidationError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Catalog source '{removed_name}' removed")
diff --git a/src/specify_cli/workflows/command_add.py b/src/specify_cli/workflows/command_add.py
new file mode 100644
index 000000000..774d57515
--- /dev/null
+++ b/src/specify_cli/workflows/command_add.py
@@ -0,0 +1,507 @@
+"""Command handler for ``specify workflow add``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
+def _cleanup_download_tmp_path(tmp_path: cli.Path | None) -> None:
+ """Best-effort unlink of a partially-downloaded workflow temp file.
+
+ A cleanup ``OSError`` here must never replace/mask whatever error or
+ interrupt is already propagating -- warn about it and keep going.
+ """
+ if tmp_path is None:
+ return
+ try:
+ tmp_path.unlink(missing_ok=True)
+ except OSError as cleanup_exc:
+ cli.console.print(
+ "[yellow]Warning:[/yellow] Could not remove temporary "
+ f"workflow download file: {cli._escape_markup(str(cleanup_exc))} "
+ f"(path: {cli._escape_markup(str(tmp_path))})"
+ )
+
+
+def _workflow_package_has_companions(package_dir: cli.Path) -> bool:
+ """Return whether a directory contains anything beyond workflow.yml."""
+ return any(path.name != "workflow.yml" for path in package_dir.iterdir())
+
+
[email protected]_app.command("add")
+def workflow_add(
+ source: str = cli.typer.Argument(..., help="Workflow ID, URL, or local path"),
+ dev: bool = cli.typer.Option(
+ False, "--dev", help="Install from a local workflow YAML file or directory"
+ ),
+ from_url: str | None = cli.typer.Option(
+ None, "--from", help="Install from a custom URL"
+ ),
+):
+ """Install a workflow from catalog, URL, or local path."""
+ from . import load_custom_steps
+ from .engine import WorkflowDefinition
+
+ project_root = cli._require_specify_project()
+ load_custom_steps(project_root)
+ cli._open_workflow_registry(project_root)
+ workflows_dir = project_root / ".specify" / "workflows"
+ # With --from, source names the expected workflow ID: validate it up
+ # front so a URL/path/typo fails without a network fetch.
+ if from_url is not None and not dev:
+ cli._validate_workflow_id_or_exit(source)
+ # Reject a symlinked .specify / .specify/workflows before any write so an
+ # install can't escape the project root (covers the local, URL, and
+ # catalog branches below — all write beneath workflows_dir).
+ cli._reject_unsafe_dir(project_root / ".specify", ".specify")
+ cli._reject_unsafe_dir(workflows_dir, ".specify/workflows")
+
+ def _validate_and_install_local(
+ yaml_path: cli.Path, source_label: str, expected_id: str | None = None
+ ) -> None:
+ """Validate and install a workflow from a local YAML file."""
+ try:
+ with yaml_path.open("rb") as source_file:
+ source_mode = cli.os.fstat(source_file.fileno()).st_mode & 0o7777
+ source_content = source_file.read()
+ definition = WorkflowDefinition.from_string(source_content.decode("utf-8"))
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to read workflow YAML: "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ except (UnicodeDecodeError, ValueError, cli.yaml.YAMLError) as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow YAML: {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ # Non-string ids (e.g. unquoted ``id: 123`` or ``id: 0``) fall through
+ # to validate_workflow below, which reports a typed error instead of
+ # crashing on ``.strip()`` here. Only None/empty/whitespace-only ids
+ # are rejected as missing.
+ if (
+ definition.id is None
+ or definition.id == ""
+ or (isinstance(definition.id, str) and not definition.id.strip())
+ ):
+ cli.console.print(
+ "[red]Error:[/red] Workflow definition has an empty or missing 'id'"
+ )
+ raise cli.typer.Exit(1)
+
+ from .engine import validate_workflow
+
+ errors = validate_workflow(definition)
+ if errors:
+ cli.console.print("[red]Error:[/red] Workflow validation failed:")
+ for err in errors:
+ cli.console.print(f" \u2022 {cli._escape_markup(str(err))}")
+ raise cli.typer.Exit(1)
+
+ if expected_id is not None and definition.id != expected_id:
+ cli.console.print(
+ f"[red]Error:[/red] Workflow ID in YAML ({cli._escape_markup(repr(definition.id))}) "
+ f"does not match the requested workflow ID ({cli._escape_markup(repr(expected_id))})."
+ )
+ raise cli.typer.Exit(1)
+
+ dest_dir = cli._safe_workflow_id_dir(workflows_dir, definition.id)
+ dest_file = dest_dir / "workflow.yml"
+ existed_before = dest_dir.is_dir()
+
+ try:
+ staged_file = cli._stage_workflow_file(dest_dir)
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to install workflow "
+ f"'{cli._escape_markup(definition.id)}': {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+
+ try:
+ # Write the exact bytes parsed above so a concurrent source edit
+ # cannot desynchronize installed content from validated metadata.
+ staged_file.write_bytes(source_content)
+ staged_file.set_mode(source_mode)
+ except OSError as exc:
+ cli._safe_discard_staged_workflow_file(
+ staged_file, dest_dir, existed_before
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to install workflow "
+ f"'{cli._escape_markup(definition.id)}': {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+
+ try:
+ transaction = cli._workflow_install_transaction(project_root)
+ with transaction:
+ transaction_existed_before = existed_before or dest_file.exists()
+ transaction_registry = cli._open_workflow_registry(project_root)
+ # Commit the staged copy onto dest_file via an atomic swap. A
+ # prior file is renamed aside so registry failure can restore it.
+ try:
+ backup_file = cli._commit_workflow_file(
+ staged_file, dest_file, transaction_existed_before
+ )
+ except OSError as exc:
+ cli._safe_discard_staged_workflow_file(
+ staged_file, dest_dir, existed_before
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to install workflow "
+ f"'{cli._escape_markup(definition.id)}': "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ try:
+ entry = {
+ "name": definition.name,
+ "version": definition.version,
+ "description": definition.description,
+ "source": source_label,
+ }
+ existing = transaction_registry.get(definition.id)
+ if isinstance(existing, dict) and not existing.get("enabled", True):
+ entry["enabled"] = False
+ transaction_registry.add(definition.id, entry)
+ except (OSError, TypeError, ValueError) as exc:
+ cli._safe_rollback_committed_workflow_file(
+ dest_file,
+ dest_dir,
+ transaction_existed_before,
+ backup_file,
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to update workflow registry for "
+ f"'{cli._escape_markup(definition.id)}': "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ # Registry update succeeded while the transaction lock is held.
+ cli._discard_committed_backup_file(backup_file)
+ except cli.typer.Exit:
+ cli._safe_discard_staged_workflow_file(
+ staged_file, dest_dir, existed_before
+ )
+ raise
+ except OSError as exc:
+ cli._safe_discard_staged_workflow_file(
+ staged_file, dest_dir, existed_before
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to lock workflow install "
+ f"'{cli._escape_markup(definition.id)}': {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ cli.console.print(
+ f"[green]✓[/green] Workflow '{cli._escape_markup(definition.name)}' "
+ f"({cli._escape_markup(definition.id)}) installed"
+ )
+
+ # Explicit local install (mirrors `extension add --dev`). --dev takes
+ # precedence over --from so a URL that would be ignored is never fetched.
+ if dev:
+ dev_path = cli.Path(source).expanduser()
+ if dev_path.is_file() and dev_path.suffix.lower() in (".yml", ".yaml"):
+ _validate_and_install_local(dev_path, str(dev_path))
+ return
+ if (
+ dev_path.is_file()
+ and cli.archive_format_from_name(str(dev_path)) is not None
+ ):
+ import tempfile
+
+ with tempfile.TemporaryDirectory(
+ prefix="speckit-workflow-archive-"
+ ) as tmpdir:
+ extracted_root = cli.Path(tmpdir)
+ try:
+ cli.safe_extract_archive(dev_path, extracted_root)
+ package_root = cli._workflow_package_root(extracted_root)
+ except ValueError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow archive: "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ cli._install_workflow_package(
+ project_root,
+ workflows_dir,
+ package_root,
+ str(dev_path),
+ )
+ return
+ if dev_path.is_dir():
+ dev_wf_file = dev_path / "workflow.yml"
+ if not dev_wf_file.is_file():
+ cli.console.print(
+ f"[red]Error:[/red] No workflow.yml found in {cli._escape_markup(source)}"
+ )
+ raise cli.typer.Exit(1)
+ if _workflow_package_has_companions(dev_path):
+ cli._install_workflow_package(
+ project_root,
+ workflows_dir,
+ dev_path,
+ str(dev_path),
+ )
+ else:
+ _validate_and_install_local(dev_wf_file, str(dev_path))
+ return
+ cli.console.print(
+ "[red]Error:[/red] --dev source must be a workflow YAML file, "
+ "supported archive, or directory containing workflow.yml: "
+ f"{cli._escape_markup(source)}"
+ )
+ raise cli.typer.Exit(1)
+
+ # Try as URL (http/https) — either the positional source is a URL, or an
+ # explicit --from URL names where to fetch it (mirrors `extension add --from`).
+ download_url = (
+ from_url
+ if from_url is not None
+ else (source if source.startswith(("http://", "https://")) else None)
+ )
+ if download_url is not None:
+ from urllib.parse import urlparse
+ from specify_cli.authentication.http import open_url as _open_url
+
+ try:
+ urlparse(download_url).port
+ except ValueError:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid URL: {cli._escape_markup(download_url)}"
+ )
+ raise cli.typer.Exit(1)
+ if not cli.is_https_or_localhost_http(download_url):
+ cli.console.print(
+ "[red]Error:[/red] Only HTTPS URLs are allowed, except HTTP for localhost."
+ )
+ raise cli.typer.Exit(1)
+
+ if from_url is not None:
+ from rich.panel import Panel
+
+ safe_url = cli._escape_markup(from_url)
+ cli.console.print()
+ cli.console.print(
+ Panel(
+ "[bold]You are installing a workflow from an external URL "
+ "that is not\nlisted in any of your configured workflow "
+ "catalogs.[/bold]\n\n"
+ f"URL: {safe_url}\n\n"
+ "Only install workflows from sources you trust.",
+ title="[bold yellow]⚠ Untrusted Source[/bold yellow]",
+ border_style="yellow",
+ padding=(1, 2),
+ )
+ )
+ cli.console.print()
+ if not cli.typer.confirm("Continue with installation?", default=False):
+ cli.console.print("Cancelled")
+ raise cli.typer.Exit(0)
+
+ from specify_cli._github_http import (
+ resolve_github_release_asset_api_url as _resolve_gh_asset,
+ )
+ from specify_cli.authentication.http import (
+ github_provider_hosts as _github_provider_hosts,
+ )
+
+ _wf_url_extra_headers = None
+ _resolved_wf_url = _resolve_gh_asset(
+ download_url,
+ _open_url,
+ timeout=30,
+ github_hosts=_github_provider_hosts(),
+ redirect_validator=cli._reject_insecure_download_redirect,
+ )
+ if _resolved_wf_url:
+ download_url = _resolved_wf_url
+ _wf_url_extra_headers = {"Accept": "application/octet-stream"}
+
+ import tempfile
+
+ tmp_path: cli.Path | None = None
+ downloaded_archive_format = None
+ try:
+ with _open_url(
+ download_url,
+ timeout=30,
+ extra_headers=_wf_url_extra_headers,
+ redirect_validator=cli._reject_insecure_download_redirect,
+ ) as resp:
+ final_url = resp.geturl()
+ if not cli.is_https_or_localhost_http(final_url):
+ cli.console.print(
+ f"[red]Error:[/red] URL redirected to non-HTTPS: {cli._escape_markup(final_url)}"
+ )
+ raise cli.typer.Exit(1)
+ content_type = (
+ resp.getheader("Content-Type")
+ if hasattr(resp, "getheader")
+ else None
+ )
+ downloaded_archive_format = (
+ cli.archive_format_from_name(final_url)
+ or cli.archive_format_from_name(download_url)
+ or cli.archive_format_from_content_type(content_type)
+ )
+ declared_yaml = cli._workflow_yaml_is_declared(final_url, content_type)
+ suffix = (
+ cli.archive_suffix(downloaded_archive_format)
+ if downloaded_archive_format is not None
+ else ".yml"
+ if declared_yaml
+ else ".download"
+ )
+ with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+ # Assign tmp_path immediately: NamedTemporaryFile(delete=False)
+ # creates the file on disk right away, before any bytes are
+ # written, so a failure in the size-limited read below must
+ # still be able to find and remove it.
+ tmp_path = cli.Path(tmp.name)
+ if downloaded_archive_format is not None:
+ downloaded_content = cli.read_response_limited(
+ resp,
+ error_type=ValueError,
+ label="workflow archive download",
+ )
+ elif declared_yaml:
+ downloaded_content = cli._read_response_within_limit(resp)
+ else:
+ downloaded_content = cli.read_response_limited(
+ resp,
+ error_type=ValueError,
+ label="workflow download",
+ )
+ downloaded_archive_format = cli._sniff_workflow_archive_format(
+ downloaded_content
+ )
+ if downloaded_archive_format is None:
+ cli._enforce_workflow_yaml_size(downloaded_content)
+ tmp.write(downloaded_content)
+ except cli.typer.Exit:
+ _cleanup_download_tmp_path(tmp_path)
+ raise
+ except Exception as exc:
+ # A cleanup failure here must never replace/mask the
+ # original download error below with a raw, unhandled
+ # OSError -- warn about it and keep going, exactly like the
+ # later post-install finally cleanup does.
+ _cleanup_download_tmp_path(tmp_path)
+ cli.console.print(
+ f"[red]Error:[/red] Failed to download workflow: {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ except BaseException:
+ # Covers KeyboardInterrupt and other non-Exception exits: the
+ # temp file is already created on disk (delete=False) by this
+ # point, so an interrupt during the size-limited read must still
+ # unlink it rather than leaking it to the system temp directory.
+ _cleanup_download_tmp_path(tmp_path)
+ raise
+ try:
+ if downloaded_archive_format is None:
+ _validate_and_install_local(
+ tmp_path,
+ download_url,
+ expected_id=source if from_url else None,
+ )
+ else:
+ with tempfile.TemporaryDirectory(
+ prefix="speckit-workflow-archive-"
+ ) as extract_dir:
+ extracted_root = cli.Path(extract_dir)
+ try:
+ cli.safe_extract_archive(
+ tmp_path,
+ extracted_root,
+ source_name=final_url,
+ content_type=content_type,
+ )
+ package_root = cli._workflow_package_root(extracted_root)
+ except ValueError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow archive: "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ cli._install_workflow_package(
+ project_root,
+ workflows_dir,
+ package_root,
+ download_url,
+ expected_id=source if from_url else None,
+ )
+ finally:
+ # Best-effort: _validate_and_install_local may already have
+ # committed the file + registry entry (success) or already
+ # raised its own clean typer.Exit (failure) by this point --
+ # either way, a cleanup OSError here must never mask that
+ # outcome or surface as its own unhandled failure. Warn instead,
+ # same as the committed-backup cleanup above.
+ try:
+ tmp_path.unlink(missing_ok=True)
+ except OSError as exc:
+ cli.console.print(
+ "[yellow]Warning:[/yellow] Could not remove temporary "
+ f"workflow download file: {cli._escape_markup(str(exc))} "
+ f"(path: {cli._escape_markup(str(tmp_path))})"
+ )
+ return
+
+ # Try as a local file/directory
+ source_path = cli.Path(source)
+ if source_path.exists():
+ if source_path.is_file() and source_path.suffix.lower() in (".yml", ".yaml"):
+ _validate_and_install_local(source_path, str(source_path))
+ return
+ elif (
+ source_path.is_file()
+ and cli.archive_format_from_name(str(source_path)) is not None
+ ):
+ import tempfile
+
+ with tempfile.TemporaryDirectory(
+ prefix="speckit-workflow-archive-"
+ ) as tmpdir:
+ extracted_root = cli.Path(tmpdir)
+ try:
+ cli.safe_extract_archive(source_path, extracted_root)
+ package_root = cli._workflow_package_root(extracted_root)
+ except ValueError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow archive: "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ cli._install_workflow_package(
+ project_root,
+ workflows_dir,
+ package_root,
+ str(source_path),
+ )
+ return
+ elif source_path.is_dir():
+ wf_file = source_path / "workflow.yml"
+ if not wf_file.is_file():
+ cli.console.print(
+ f"[red]Error:[/red] No workflow.yml found in {cli._escape_markup(source)}"
+ )
+ raise cli.typer.Exit(1)
+ if _workflow_package_has_companions(source_path):
+ cli._install_workflow_package(
+ project_root,
+ workflows_dir,
+ source_path,
+ str(source_path),
+ )
+ else:
+ _validate_and_install_local(wf_file, str(source_path))
+ return
+
+ # Try from catalog
+ cli._install_workflow_from_catalog(project_root, workflows_dir, source)
diff --git a/src/specify_cli/workflows/command_disable.py b/src/specify_cli/workflows/command_disable.py
new file mode 100644
index 000000000..83948e973
--- /dev/null
+++ b/src/specify_cli/workflows/command_disable.py
@@ -0,0 +1,16 @@
+"""Command handler for ``specify workflow disable``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("disable")
+def workflow_disable(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID to disable"),
+):
+ """Disable a workflow without removing it."""
+ cli._set_workflow_enabled(workflow_id, False)
+ cli.console.print(
+ f"To re-enable: specify workflow enable {cli._escape_markup(workflow_id)}"
+ )
diff --git a/src/specify_cli/workflows/command_enable.py b/src/specify_cli/workflows/command_enable.py
new file mode 100644
index 000000000..e0819cdda
--- /dev/null
+++ b/src/specify_cli/workflows/command_enable.py
@@ -0,0 +1,13 @@
+"""Command handler for ``specify workflow enable``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("enable")
+def workflow_enable(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID to enable"),
+):
+ """Enable a disabled workflow."""
+ cli._set_workflow_enabled(workflow_id, True)
diff --git a/src/specify_cli/workflows/command_info.py b/src/specify_cli/workflows/command_info.py
new file mode 100644
index 000000000..ba3741f7b
--- /dev/null
+++ b/src/specify_cli/workflows/command_info.py
@@ -0,0 +1,121 @@
+"""Command handler for ``specify workflow info``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("info")
+def workflow_info(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID"),
+):
+ """Show workflow details and step graph."""
+ from .catalog import WorkflowCatalog, WorkflowCatalogError
+ from .engine import WorkflowEngine
+
+ project_root = cli._require_specify_project()
+
+ # Check installed first
+ registry = cli._open_workflow_registry(project_root)
+ installed = registry.get(workflow_id)
+
+ engine = WorkflowEngine(project_root)
+
+ definition = None
+ try:
+ definition = engine.load_workflow(workflow_id)
+ except FileNotFoundError:
+ # Local workflow definition not found on disk; fall back to
+ # catalog/registry lookup below.
+ pass
+ except ValueError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow: {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+
+ if definition:
+ # Escape every user-controlled field: workflow.yml values (name,
+ # version, author, description, integration, input names/types) are not
+ # trusted, and console.print has Rich markup enabled, so an unescaped
+ # `[...]` in any of them is parsed as a style tag and silently swallowed
+ # (same defect fixed for the step graph below; the sibling workflow_list
+ # already escapes all of these).
+ cli.console.print(
+ f"\n[bold cyan]{cli._escape_markup(str(definition.name))}[/bold cyan] "
+ f"({cli._escape_markup(str(definition.id))})"
+ )
+ cli.console.print(
+ f" Version: {cli._escape_markup(str(definition.version))}"
+ )
+ if definition.author:
+ cli.console.print(
+ f" Author: {cli._escape_markup(str(definition.author))}"
+ )
+ if definition.description:
+ cli.console.print(
+ f" Description: {cli._escape_markup(str(definition.description))}"
+ )
+ if definition.default_integration:
+ cli.console.print(
+ f" Integration: {cli._escape_markup(str(definition.default_integration))}"
+ )
+ if installed:
+ cli.console.print(" [green]Installed[/green]")
+
+ if definition.inputs:
+ cli.console.print("\n [bold]Inputs:[/bold]")
+ for name, inp in definition.inputs.items():
+ if isinstance(inp, dict):
+ req = "required" if inp.get("required") else "optional"
+ cli.console.print(
+ f" {cli._escape_markup(str(name))} "
+ f"({cli._escape_markup(str(inp.get('type', 'string')))}) — {req}"
+ )
+
+ if definition.steps:
+ cli.console.print(f"\n [bold]Steps ({len(definition.steps)}):[/bold]")
+ for step in definition.steps:
+ stype = step.get("type", "command")
+ # Escape the literal bracket (\[) so Rich renders `[<type>]`
+ # instead of parsing it as a style tag named after the step
+ # type (which it silently swallows); escape id/type too, as
+ # the sibling workflow_list does. Mirrors the `\[disabled]`
+ # precedent above.
+ cli.console.print(
+ f" → {cli._escape_markup(str(step.get('id', '?')))} "
+ f"\\[{cli._escape_markup(str(stype))}]"
+ )
+ return
+
+ # Try catalog
+ catalog = WorkflowCatalog(project_root)
+ try:
+ info = catalog.get_workflow_info(workflow_id)
+ except WorkflowCatalogError:
+ info = None
+
+ if info:
+ # Catalog-derived fields are untrusted; escape them so bracketed content
+ # is rendered literally rather than parsed (and swallowed) as Rich markup.
+ cli.console.print(
+ f"\n[bold cyan]{cli._escape_markup(str(info.get('name', workflow_id)))}[/bold cyan] "
+ f"({cli._escape_markup(str(workflow_id))})"
+ )
+ cli.console.print(
+ f" Version: {cli._escape_markup(str(info.get('version', '?')))}"
+ )
+ if info.get("description"):
+ cli.console.print(
+ f" Description: {cli._escape_markup(str(info['description']))}"
+ )
+ info_tags = info.get("tags", [])
+ if isinstance(info_tags, list) and info_tags:
+ safe_tags = cli._escape_markup(", ".join(str(t) for t in info_tags))
+ cli.console.print(f" Tags: {safe_tags}")
+ cli.console.print(" [yellow]Not installed[/yellow]")
+ else:
+ cli.console.print(
+ f"[red]Error:[/red] Workflow '{cli._escape_markup(str(workflow_id))}' not found"
+ )
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/command_list.py b/src/specify_cli/workflows/command_list.py
new file mode 100644
index 000000000..69cc3be39
--- /dev/null
+++ b/src/specify_cli/workflows/command_list.py
@@ -0,0 +1,36 @@
+"""Command handler for ``specify workflow list``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("list")
+def workflow_list():
+ """List installed workflows."""
+ project_root = cli._require_specify_project()
+ registry = cli._open_workflow_registry(project_root)
+ installed = registry.list()
+
+ if not installed:
+ cli.console.print("[yellow]No workflows installed.[/yellow]")
+ cli.console.print("\nInstall a workflow with:")
+ cli.console.print(" [cyan]specify workflow add <workflow-id>[/cyan]")
+ return
+
+ cli.console.print("\n[bold cyan]Installed Workflows:[/bold cyan]\n")
+ for wf_id, wf_data in installed.items():
+ safe_id = cli._escape_markup(wf_id)
+ if not isinstance(wf_data, dict):
+ cli.console.print(
+ f" [yellow]Warning:[/yellow] Skipping corrupted registry entry '{safe_id}'.\n"
+ )
+ continue
+ marker = "" if wf_data.get("enabled", True) else " [red]\\[disabled][/red]"
+ name = cli._escape_markup(str(wf_data.get("name", wf_id)))
+ version = cli._escape_markup(str(wf_data.get("version", "?")))
+ cli.console.print(f" [bold]{name}[/bold] ({safe_id}) v{version}{marker}")
+ desc = wf_data.get("description", "")
+ if desc:
+ cli.console.print(f" {cli._escape_markup(str(desc))}")
+ cli.console.print()
diff --git a/src/specify_cli/workflows/command_remove.py b/src/specify_cli/workflows/command_remove.py
new file mode 100644
index 000000000..7c3a68af7
--- /dev/null
+++ b/src/specify_cli/workflows/command_remove.py
@@ -0,0 +1,127 @@
+"""Command handler for ``specify workflow remove``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
+def _remove_workflow_locked(
+ project_root: cli.Path, workflows_dir: cli.Path, workflow_id: str
+) -> cli.Path | None:
+ """Stage a workflow directory and persist removal while locked."""
+ registry = cli._open_workflow_registry(project_root)
+ safe_id = cli._escape_markup(workflow_id)
+ if not registry.is_installed(workflow_id):
+ cli.console.print(f"[red]Error:[/red] Workflow '{safe_id}' is not installed")
+ raise cli.typer.Exit(1)
+
+ workflow_dir_unresolved = workflows_dir / workflow_id
+ if workflow_dir_unresolved.is_symlink():
+ cli.console.print(
+ f"[red]Error:[/red] Refusing to remove symlinked "
+ f".specify/workflows/{safe_id}"
+ )
+ raise cli.typer.Exit(1)
+
+ workflow_dir = workflow_dir_unresolved.resolve()
+ try:
+ rel_parts = workflow_dir.relative_to(workflows_dir.resolve()).parts
+ except ValueError:
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow ID: "
+ f"{cli._escape_markup(repr(workflow_id))}"
+ )
+ raise cli.typer.Exit(1)
+ if rel_parts != (workflow_id,):
+ cli.console.print(
+ f"[red]Error:[/red] Invalid workflow ID: "
+ f"{cli._escape_markup(repr(workflow_id))}"
+ )
+ raise cli.typer.Exit(1)
+
+ if workflow_dir.exists() and not workflow_dir.is_dir():
+ cli.console.print(
+ f"[red]Error:[/red] .specify/workflows/{safe_id} exists "
+ "but is not a directory"
+ )
+ raise cli.typer.Exit(1)
+
+ import tempfile
+
+ staged_dir: cli.Path | None = None
+ if workflow_dir.exists():
+ try:
+ reserved = cli.Path(
+ tempfile.mkdtemp(prefix=f".{workflow_id}.removing-", dir=workflows_dir)
+ )
+ reserved.rmdir()
+ cli.os.rename(workflow_dir, reserved)
+ staged_dir = reserved
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to stage workflow directory "
+ f"{cli._escape_markup(str(workflow_dir))} for removal: "
+ f"{cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+
+ try:
+ registry.remove(workflow_id)
+ except (OSError, TypeError, ValueError) as exc:
+ if staged_dir is not None:
+ try:
+ cli.os.rename(staged_dir, workflow_dir)
+ except OSError as restore_exc:
+ cli.console.print(
+ f"[yellow]Warning:[/yellow] Failed to restore workflow "
+ "directory after registry update failure; it remains "
+ f"staged at {cli._escape_markup(str(staged_dir))}: "
+ f"{cli._escape_markup(str(restore_exc))}"
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to update workflow registry for "
+ f"'{safe_id}': {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+ return staged_dir
+
+
[email protected]_app.command("remove")
+def workflow_remove(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID to uninstall"),
+):
+ """Uninstall a workflow."""
+ project_root = cli._require_specify_project()
+ workflows_dir = project_root / ".specify" / "workflows"
+ cli._validate_workflow_id_or_exit(workflow_id)
+ safe_id = cli._escape_markup(workflow_id)
+ import shutil
+
+ try:
+ with cli._workflow_install_transaction(project_root):
+ staged_dir = _remove_workflow_locked(
+ project_root, workflows_dir, workflow_id
+ )
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to lock workflow removal "
+ f"'{safe_id}': {cli._escape_markup(str(exc))}"
+ )
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Workflow '{workflow_id}' removed")
+
+ # The registry has already durably committed the removal at this point,
+ # so it must stand regardless of what happens below: deleting the staged
+ # directory is now just cleanup, not a data-integrity concern, and a
+ # failure here is reported as a warning (not an error) to avoid
+ # contradicting the registry state that already succeeded.
+ if staged_dir is not None:
+ try:
+ shutil.rmtree(staged_dir)
+ except OSError as exc:
+ cli.console.print(
+ f"[yellow]Warning:[/yellow] Workflow '{safe_id}' was removed, but its "
+ f"staged directory could not be deleted: {cli._escape_markup(str(exc))}. "
+ f"Remove it manually: {cli._escape_markup(str(staged_dir))}"
+ )
diff --git a/src/specify_cli/workflows/command_resolve.py b/src/specify_cli/workflows/command_resolve.py
new file mode 100644
index 000000000..6caa4e625
--- /dev/null
+++ b/src/specify_cli/workflows/command_resolve.py
@@ -0,0 +1,17 @@
+"""Command handler for ``specify workflow resolve``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("resolve")
+def workflow_resolve_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID to resolve"),
+):
+ """Show layer attribution for a resolved workflow."""
+ from .overlay.operations import workflow_resolve
+
+ project_root = cli._require_specify_project()
+ if workflow_resolve(project_root, workflow_id) is None:
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/command_resume.py b/src/specify_cli/workflows/command_resume.py
new file mode 100644
index 000000000..3be24f958
--- /dev/null
+++ b/src/specify_cli/workflows/command_resume.py
@@ -0,0 +1,113 @@
+"""Command handler for ``specify workflow resume``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+from . import _command_resume_state as resume_state
+
+
[email protected]_app.command("resume")
+def workflow_resume(
+ run_id: str = cli.typer.Argument(..., help="Run ID to resume"),
+ input_values: list[str] | None = cli.typer.Option(
+ None, "--input", "-i", help="Updated input values as key=value pairs"
+ ),
+ json_output: bool = cli.typer.Option(
+ False,
+ "--json",
+ help="Emit the resume outcome as a single JSON object instead of formatted text.",
+ ),
+):
+ """Resume a paused or failed workflow run."""
+ from . import load_custom_steps
+ from .engine import RunState, WorkflowEngine
+
+ project_root = cli._require_specify_project()
+ load_custom_steps(project_root)
+ engine = WorkflowEngine(project_root)
+ 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"
+ )
+
+ inputs = cli._parse_input_values(input_values, json_output=json_output)
+ err = cli._error_console(json_output)
+
+ # Pre-load the persisted run state so a run started from an installed
+ # workflow that has since been disabled cannot resume unchecked --
+ # engine.resume() replays the run directly from disk with no registry
+ # awareness at all, which would otherwise bypass the same disabled
+ # guard `workflow run` enforces. Runs without installed_workflow_id
+ # (a direct/non-installed source, or a run persisted before this field
+ # existed) are unaffected and resume exactly as before.
+ try:
+ pre_state = RunState.load(run_id, project_root)
+ except FileNotFoundError:
+ err.print(f"[red]Error:[/red] Run not found: {run_id}")
+ raise cli.typer.Exit(1)
+ except ValueError as exc:
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ except OSError as exc:
+ err.print(f"[red]Resume failed:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+
+ if pre_state.installed_workflow_id is not None:
+ try:
+ owner_root = resume_state._resolve_run_owner_root(
+ pre_state.installed_registry_root, project_root
+ )
+ except ValueError as exc:
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ cli._require_enabled_workflow(owner_root, pre_state.installed_workflow_id, err)
+ elif not pre_state.installed_origin_tracked:
+ if cli._require_enabled_workflow(project_root, pre_state.workflow_id, err):
+ pre_state.installed_workflow_id = pre_state.workflow_id
+ pre_state.installed_origin_tracked = True
+ try:
+ pre_state.save()
+ except OSError as exc:
+ err.print(f"[red]Resume failed:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+
+ try:
+ with cli._stdout_to_stderr_when(json_output):
+ state = engine.resume(run_id, inputs or None)
+ except FileNotFoundError:
+ err.print(f"[red]Error:[/red] Run not found: {run_id}")
+ raise cli.typer.Exit(1)
+ except ValueError as exc:
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ except Exception as exc:
+ err.print(f"[red]Resume 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}]")
+
+ err_msg = cli._failed_step_error(state)
+ if err_msg:
+ cli.console.print(f"[red]Error:[/red] {cli._escape_markup(err_msg)}")
+
+ raise cli.typer.Exit(cli._run_outcome_exit_code(state.status.value))
diff --git a/src/specify_cli/workflows/command_run.py b/src/specify_cli/workflows/command_run.py
new file mode 100644
index 000000000..d966fd71e
--- /dev/null
+++ b/src/specify_cli/workflows/command_run.py
@@ -0,0 +1,168 @@
+"""Command handler for ``specify workflow run``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+from . import _command_run_ownership as run_ownership
+
+
[email protected]_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 . 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()
+ cli._reject_unsafe_workflow_storage(project_root)
+ else:
+ project_root = cli._require_specify_project()
+
+ load_custom_steps(project_root)
+ engine = WorkflowEngine(project_root)
+ 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 ValueError as exc:
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ except Exception as exc:
+ 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))
diff --git a/src/specify_cli/workflows/command_search.py b/src/specify_cli/workflows/command_search.py
new file mode 100644
index 000000000..57d9d0f5b
--- /dev/null
+++ b/src/specify_cli/workflows/command_search.py
@@ -0,0 +1,43 @@
+"""Command handler for ``specify workflow search``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("search")
+def workflow_search(
+ query: str | None = cli.typer.Argument(None, help="Search query"),
+ tag: str | None = cli.typer.Option(None, "--tag", help="Filter by tag"),
+ author: str | None = cli.typer.Option(None, "--author", help="Filter by author"),
+):
+ """Search workflow catalogs."""
+ from .catalog import WorkflowCatalog, WorkflowCatalogError
+
+ project_root = cli._require_specify_project()
+ catalog = WorkflowCatalog(project_root)
+
+ try:
+ results = catalog.search(query=query, tag=tag, author=author)
+ except WorkflowCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+
+ if not results:
+ cli.console.print("[yellow]No workflows found.[/yellow]")
+ return
+
+ cli.console.print(f"\n[bold cyan]Workflows ({len(results)}):[/bold cyan]\n")
+ for wf in results:
+ name = cli._escape_markup(str(wf.get("name", wf.get("id", "?"))))
+ wf_id = cli._escape_markup(str(wf.get("id", "?")))
+ version = cli._escape_markup(str(wf.get("version", "?")))
+ cli.console.print(f" [bold]{name}[/bold] ({wf_id}) v{version}")
+ desc = wf.get("description", "")
+ if desc:
+ cli.console.print(f" {cli._escape_markup(str(desc))}")
+ tags = wf.get("tags", [])
+ if isinstance(tags, list) and tags:
+ safe_tags = cli._escape_markup(", ".join(str(t) for t in tags))
+ cli.console.print(f" [dim]Tags: {safe_tags}[/dim]")
+ cli.console.print()
diff --git a/src/specify_cli/workflows/command_status.py b/src/specify_cli/workflows/command_status.py
new file mode 100644
index 000000000..d9af4b48d
--- /dev/null
+++ b/src/specify_cli/workflows/command_status.py
@@ -0,0 +1,129 @@
+"""Command handler for ``specify workflow status``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("status")
+def workflow_status(
+ run_id: str | None = cli.typer.Argument(
+ None, help="Run ID to inspect (shows all if omitted)"
+ ),
+ json_output: bool = cli.typer.Option(
+ False,
+ "--json",
+ help="Emit run status as a single JSON object instead of formatted text.",
+ ),
+):
+ """Show workflow run status."""
+ from .engine import WorkflowEngine
+
+ project_root = cli._require_specify_project()
+ engine = WorkflowEngine(project_root)
+
+ if run_id:
+ # Route errors to stderr under --json so the stdout JSON stream stays
+ # parseable (mirrors `workflow run`/`workflow resume`); both handlers
+ # fire before the json_output branch below.
+ err = cli._error_console(json_output)
+ try:
+ from .engine import RunState
+
+ state = RunState.load(run_id, project_root)
+ except FileNotFoundError:
+ err.print(f"[red]Error:[/red] Run not found: {run_id}")
+ raise cli.typer.Exit(1)
+ except ValueError as exc:
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ except OSError as exc:
+ # An unreadable state.json (bad permissions, a directory in its
+ # place, I/O error) must fail as cleanly as the malformed-JSON
+ # case above -- `workflow resume` already handles OSError here.
+ err.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+
+ if json_output:
+ # Build on the shared run/resume payload so the common fields
+ # (including current_step_index) stay identical across commands.
+ payload = {
+ **cli._workflow_run_payload(state),
+ "created_at": state.created_at,
+ "updated_at": state.updated_at,
+ "steps": {
+ sid: sd.get("status", "unknown")
+ for sid, sd in state.step_results.items()
+ },
+ }
+ cli._emit_workflow_json(payload)
+ return
+
+ status_colors = {
+ "completed": "green",
+ "paused": "yellow",
+ "failed": "red",
+ "aborted": "red",
+ "running": "blue",
+ "created": "dim",
+ }
+ color = status_colors.get(state.status.value, "white")
+
+ cli.console.print(f"\n[bold cyan]Workflow Run: {state.run_id}[/bold cyan]")
+ cli.console.print(f" Workflow: {state.workflow_id}")
+ cli.console.print(f" Status: [{color}]{state.status.value}[/{color}]")
+ cli.console.print(f" Created: {state.created_at}")
+ cli.console.print(f" Updated: {state.updated_at}")
+
+ if state.current_step_id:
+ cli.console.print(f" Current: {state.current_step_id}")
+
+ err_msg = cli._failed_step_error(state)
+ if err_msg:
+ cli.console.print(f" [red]Error: {cli._escape_markup(err_msg)}[/red]")
+
+ if state.step_results:
+ cli.console.print(f"\n [bold]Steps ({len(state.step_results)}):[/bold]")
+ for step_id, step_data in state.step_results.items():
+ s = step_data.get("status", "unknown")
+ sc = {"completed": "green", "failed": "red", "paused": "yellow"}.get(
+ s, "white"
+ )
+ cli.console.print(f" [{sc}]●[/{sc}] {step_id}: {s}")
+ else:
+ runs = engine.list_runs()
+
+ if json_output:
+ payload = {
+ "runs": [
+ {
+ "run_id": r["run_id"],
+ "workflow_id": r.get("workflow_id"),
+ "status": r.get("status", "unknown"),
+ "updated_at": r.get("updated_at"),
+ }
+ for r in runs
+ ]
+ }
+ cli._emit_workflow_json(payload)
+ return
+
+ if not runs:
+ cli.console.print("[yellow]No workflow runs found.[/yellow]")
+ return
+
+ cli.console.print("\n[bold cyan]Workflow Runs:[/bold cyan]\n")
+ for run_data in runs:
+ s = run_data.get("status", "unknown")
+ sc = {
+ "completed": "green",
+ "failed": "red",
+ "paused": "yellow",
+ "running": "blue",
+ }.get(s, "white")
+ cli.console.print(
+ f" [{sc}]●[/{sc}] {run_data['run_id']} "
+ f"{run_data.get('workflow_id', '?')} "
+ f"[{sc}]{s}[/{sc}] "
+ f"[dim]{run_data.get('updated_at', '?')}[/dim]"
+ )
diff --git a/src/specify_cli/workflows/command_update.py b/src/specify_cli/workflows/command_update.py
new file mode 100644
index 000000000..84ecc530e
--- /dev/null
+++ b/src/specify_cli/workflows/command_update.py
@@ -0,0 +1,148 @@
+"""Command handler for ``specify workflow update``."""
+
+from __future__ import annotations
+
+from . import _commands as cli
+
+
[email protected]_app.command("update")
+def workflow_update(
+ workflow_id: str | None = cli.typer.Argument(
+ None, help="Workflow ID to update (default: all)"
+ ),
+):
+ """Update installed workflow(s) to the latest catalog version."""
+ from packaging import version as pkg_version
+
+ from .catalog import WorkflowCatalog, WorkflowCatalogError
+
+ project_root = cli._require_specify_project()
+ registry = cli._open_workflow_registry(project_root)
+ workflows_dir = project_root / ".specify" / "workflows"
+ cli._reject_unsafe_dir(project_root / ".specify", ".specify")
+ cli._reject_unsafe_dir(workflows_dir, ".specify/workflows")
+
+ installed = registry.list()
+ if workflow_id:
+ if not registry.is_installed(workflow_id):
+ cli.console.print(
+ f"[red]Error:[/red] Workflow '{cli._escape_markup(workflow_id)}' is not installed"
+ )
+ raise cli.typer.Exit(1)
+ targets = [workflow_id]
+ else:
+ targets = list(installed)
+
+ if not targets:
+ cli.console.print("[yellow]No workflows installed[/yellow]")
+ raise cli.typer.Exit(0)
+
+ catalog = WorkflowCatalog(project_root)
+ cli.console.print("🔄 Checking for updates...\n")
+
+ updates_available: list[dict[str, str]] = []
+ checked = 0
+ for wf_id in targets:
+ safe_id = cli._escape_markup(str(wf_id))
+ metadata = installed.get(wf_id)
+ if not isinstance(metadata, dict):
+ cli.console.print(f"⚠ {safe_id}: Registry entry is corrupted (skipping)")
+ continue
+ if metadata.get("source") != "catalog":
+ cli.console.print(
+ f"⚠ {safe_id}: Not installed from a catalog — re-add to update (skipping)"
+ )
+ continue
+ try:
+ installed_version = pkg_version.Version(str(metadata.get("version")))
+ except pkg_version.InvalidVersion:
+ cli.console.print(
+ f"⚠ {safe_id}: Invalid installed version '{cli._escape_markup(str(metadata.get('version')))}' in registry (skipping)"
+ )
+ continue
+ try:
+ info = catalog.get_workflow_info(wf_id)
+ except WorkflowCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")
+ raise cli.typer.Exit(1)
+ if not info:
+ cli.console.print(f"⚠ {safe_id}: Not found in catalog (skipping)")
+ continue
+ if not info.get("_install_allowed", True):
+ cli.console.print(
+ f"⚠ {safe_id}: Updates not allowed from '{cli._escape_markup(str(info.get('_catalog_name', 'catalog')))}' (skipping)"
+ )
+ continue
+ try:
+ catalog_version = pkg_version.Version(str(info.get("version")))
+ except pkg_version.InvalidVersion:
+ cli.console.print(
+ f"⚠ {safe_id}: Invalid catalog version '{cli._escape_markup(str(info.get('version')))}' (skipping)"
+ )
+ continue
+ if catalog_version > installed_version:
+ checked += 1
+ updates_available.append(
+ {
+ "id": wf_id,
+ "installed": str(installed_version),
+ "available": str(catalog_version),
+ }
+ )
+ else:
+ checked += 1
+ cli.console.print(f"✓ {safe_id}: Up to date (v{installed_version})")
+
+ if not updates_available:
+ if not checked:
+ cli.console.print(
+ "\n[yellow]No workflows were eligible for update[/yellow]"
+ )
+ elif checked == len(targets):
+ cli.console.print("\n[green]All workflows are up to date![/green]")
+ else:
+ cli.console.print(
+ f"\n[green]All checked workflows are up to date[/green] "
+ f"[yellow]({len(targets) - checked} skipped)[/yellow]"
+ )
+ raise cli.typer.Exit(0)
+
+ cli.console.print("\n[bold]Updates available:[/bold]\n")
+ for update in updates_available:
+ cli.console.print(
+ f" • {cli._escape_markup(update['id'])}: {update['installed']} → {update['available']}"
+ )
+ cli.console.print()
+ if not cli.typer.confirm("Update these workflows?"):
+ cli.console.print("Cancelled")
+ raise cli.typer.Exit(0)
+
+ cli.console.print()
+ failed: list[str] = []
+ for update in updates_available:
+ # _install_workflow_from_catalog is fully transactional (staged
+ # download, atomic commit, rename-based rollback on registry
+ # failure): it never leaves a partially-written workflow.yml, so
+ # this loop only needs to record success/failure, not perform its
+ # own backup/restore.
+ try:
+ cli._install_workflow_from_catalog(
+ project_root,
+ workflows_dir,
+ update["id"],
+ expected_version=update["available"],
+ expected_installed_version=update["installed"],
+ )
+ except (cli.typer.Exit, OSError) as exc:
+ if isinstance(exc, OSError):
+ cli.console.print(
+ f"[red]Error:[/red] Filesystem error updating "
+ f"'{cli._escape_markup(update['id'])}': {cli._escape_markup(str(exc))}"
+ )
+ failed.append(update["id"])
+
+ if failed:
+ cli.console.print(
+ f"\n[red]Failed to update:[/red] {', '.join(cli._escape_markup(f) for f in failed)}"
+ )
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.py
index a72f6f089..f6d5a2a66 100644
--- a/src/specify_cli/workflows/engine.py
+++ b/src/specify_cli/workflows/engine.py
@@ -948,7 +948,7 @@ class WorkflowEngine:
ValueError:
If the workflow YAML is invalid.
"""
- from .overlays import WorkflowResolver
+ from .overlay import WorkflowResolver
path = Path(source).expanduser()
diff --git a/src/specify_cli/workflows/overlay/__init__.py b/src/specify_cli/workflows/overlay/__init__.py
new file mode 100644
index 000000000..935f788bd
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/__init__.py
@@ -0,0 +1,39 @@
+"""Workflow overlay domain API and nested CLI registration."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+import typer
+
+overlay_app = typer.Typer(
+ name="overlay",
+ help="Manage workflow overlays",
+ add_completion=False,
+)
+
+
+def register(app: typer.Typer) -> None:
+ """Attach the overlay command group to the workflow app."""
+ from . import command_add # noqa: F401 -- registers handler
+ from . import command_set_priority # noqa: F401 -- registers handler
+ from . import command_enable # noqa: F401 -- registers handler
+ from . import command_disable # noqa: F401 -- registers handler
+ from . import command_remove # noqa: F401 -- registers handler
+ from . import command_list # noqa: F401 -- registers handler
+
+ app.add_typer(overlay_app, name="overlay")
+
+
+def __getattr__(name: str) -> Any:
+ """Load the resolver only when the domain API is requested."""
+ if name != "WorkflowResolver":
+ raise AttributeError(name)
+ resolver = import_module(f"{__name__}.resolver")
+ value = resolver.WorkflowResolver
+ globals()[name] = value
+ return value
+
+
+__all__ = ["WorkflowResolver"]
diff --git a/src/specify_cli/workflows/overlay/command_add.py b/src/specify_cli/workflows/overlay/command_add.py
new file mode 100644
index 000000000..9af10ca28
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_add.py
@@ -0,0 +1,23 @@
+"""Command handler for ``specify workflow overlay add``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("add")
+def workflow_overlay_add_cmd(
+ source: cli.Path = cli.typer.Argument(..., help="Path to overlay YAML file"),
+ priority: int = cli.typer.Option(
+ 10,
+ "--priority",
+ help="Resolution priority (lower = higher precedence, default 10)",
+ ),
+):
+ """Add a project-local overlay for a workflow."""
+ from .operations import workflow_overlay_add
+
+ project_root = cli._require_specify_project()
+ if workflow_overlay_add(project_root, source, priority) is None:
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlay/command_disable.py b/src/specify_cli/workflows/overlay/command_disable.py
new file mode 100644
index 000000000..ffcc4de30
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_disable.py
@@ -0,0 +1,19 @@
+"""Command handler for ``specify workflow overlay disable``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("disable")
+def workflow_overlay_disable_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID the overlay extends"),
+ overlay_id: str = cli.typer.Argument(..., help="Overlay ID"),
+):
+ """Disable a project-local overlay."""
+ from .operations import workflow_overlay_disable
+
+ project_root = cli._require_specify_project()
+ if not workflow_overlay_disable(project_root, workflow_id, overlay_id):
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlay/command_enable.py b/src/specify_cli/workflows/overlay/command_enable.py
new file mode 100644
index 000000000..7a07eaee6
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_enable.py
@@ -0,0 +1,19 @@
+"""Command handler for ``specify workflow overlay enable``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("enable")
+def workflow_overlay_enable_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID the overlay extends"),
+ overlay_id: str = cli.typer.Argument(..., help="Overlay ID"),
+):
+ """Enable a project-local overlay."""
+ from .operations import workflow_overlay_enable
+
+ project_root = cli._require_specify_project()
+ if not workflow_overlay_enable(project_root, workflow_id, overlay_id):
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlay/command_list.py b/src/specify_cli/workflows/overlay/command_list.py
new file mode 100644
index 000000000..da93d73ef
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_list.py
@@ -0,0 +1,18 @@
+"""Command handler for ``specify workflow overlay list``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("list")
+def workflow_overlay_list_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID"),
+):
+ """List overlays for a workflow."""
+ from .operations import workflow_overlay_list
+
+ project_root = cli._require_specify_project()
+ if workflow_overlay_list(project_root, workflow_id) is None:
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlay/command_remove.py b/src/specify_cli/workflows/overlay/command_remove.py
new file mode 100644
index 000000000..8e3db9bc6
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_remove.py
@@ -0,0 +1,19 @@
+"""Command handler for ``specify workflow overlay remove``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("remove")
+def workflow_overlay_remove_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID the overlay extends"),
+ overlay_id: str = cli.typer.Argument(..., help="Overlay ID"),
+):
+ """Remove a project-local overlay."""
+ from .operations import workflow_overlay_remove
+
+ project_root = cli._require_specify_project()
+ if not workflow_overlay_remove(project_root, workflow_id, overlay_id):
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlay/command_set_priority.py b/src/specify_cli/workflows/overlay/command_set_priority.py
new file mode 100644
index 000000000..e2734fd6d
--- /dev/null
+++ b/src/specify_cli/workflows/overlay/command_set_priority.py
@@ -0,0 +1,24 @@
+"""Command handler for ``specify workflow overlay set-priority``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import overlay_app
+
+
+@overlay_app.command("set-priority")
+def workflow_overlay_set_priority_cmd(
+ workflow_id: str = cli.typer.Argument(..., help="Workflow ID the overlay extends"),
+ overlay_id: str = cli.typer.Argument(..., help="Overlay ID"),
+ priority: int = cli.typer.Argument(
+ ..., help="New priority (lower = higher precedence)"
+ ),
+):
+ """Set the priority of a project-local overlay."""
+ from .operations import workflow_overlay_set_priority
+
+ project_root = cli._require_specify_project()
+ if not workflow_overlay_set_priority(
+ project_root, workflow_id, overlay_id, priority
+ ):
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/overlays/composer.py b/src/specify_cli/workflows/overlay/composer.py
similarity index 100%
rename from src/specify_cli/workflows/overlays/composer.py
rename to src/specify_cli/workflows/overlay/composer.py
diff --git a/src/specify_cli/workflows/overlays/layer_sources.py b/src/specify_cli/workflows/overlay/layer_sources.py
similarity index 100%
rename from src/specify_cli/workflows/overlays/layer_sources.py
rename to src/specify_cli/workflows/overlay/layer_sources.py
diff --git a/src/specify_cli/workflows/overlays/merge.py b/src/specify_cli/workflows/overlay/merge.py
similarity index 100%
rename from src/specify_cli/workflows/overlays/merge.py
rename to src/specify_cli/workflows/overlay/merge.py
diff --git a/src/specify_cli/workflows/overlays/_commands.py b/src/specify_cli/workflows/overlay/operations.py
similarity index 93%
rename from src/specify_cli/workflows/overlays/_commands.py
rename to src/specify_cli/workflows/overlay/operations.py
index 156e0d6c0..ab390774c 100644
--- a/src/specify_cli/workflows/overlays/_commands.py
+++ b/src/specify_cli/workflows/overlay/operations.py
@@ -1,4 +1,4 @@
-"""CLI handlers for ``specify workflow overlay *`` and ``specify workflow resolve``."""
+"""Domain operations used by workflow overlay and resolve commands."""
from __future__ import annotations
@@ -12,14 +12,7 @@ from rich.markup import escape as _escape_markup
from ..._console import console, err_console
from ...extensions import normalize_priority
-from .._commands import (
- _commit_workflow_file,
- _discard_committed_backup_file,
- _reject_unsafe_dir,
- _reject_unsafe_workflow_storage,
- _safe_discard_staged_workflow_file,
- _stage_workflow_file,
-)
+from .. import _commands as cli
from . import WorkflowResolver
from .schema import _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN, validate_overlay_yaml
@@ -50,9 +43,9 @@ def _validate_workflow_id_or_exit(workflow_id: str) -> None:
def _overlay_root(project_root: Path) -> Path:
"""Return the project-local overlay root after rejecting unsafe ancestors."""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
root = project_root / ".specify" / "workflows" / "overlays"
- _reject_unsafe_dir(root, ".specify/workflows/overlays")
+ cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
return root
@@ -72,7 +65,7 @@ def _ensure_contained_dir(path: Path, root: Path) -> Path:
Returns *path* if safe. Raises typer.Exit on traversal or symlink.
"""
- _reject_unsafe_dir(root, ".specify/workflows/overlays")
+ cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
if path.is_symlink():
err_console.print(
f"[red]Error:[/red] Refusing to use symlinked path {path}."
@@ -134,7 +127,7 @@ def _find_overlay_file(project_root: Path, workflow_id: str, overlay_id: str) ->
def _ensure_contained_path(path: Path, root: Path) -> Path:
"""Return *path* only if it resolves inside *root*; otherwise raise typer.Exit."""
- _reject_unsafe_dir(root, ".specify/workflows/overlays")
+ cli._reject_unsafe_dir(root, ".specify/workflows/overlays")
if path.is_symlink():
err_console.print(
f"[red]Error:[/red] Refusing to use symlinked path {path}."
@@ -176,7 +169,7 @@ def workflow_overlay_add(
Returns the path of the installed overlay file, or None on failure.
"""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
data, errors = _read_overlay(source)
if data is None:
for err in errors:
@@ -258,7 +251,7 @@ def workflow_overlay_add(
try:
target_dir.mkdir(parents=True, exist_ok=True)
existed_before = target_path.exists()
- staged = _stage_workflow_file(target_path.parent)
+ staged = cli._stage_workflow_file(target_path.parent)
try:
# ``allow_unicode=True`` matches every other YAML writer in the
# repo. Without it every non-ASCII character in a hand-authored
@@ -269,16 +262,16 @@ def workflow_overlay_add(
"utf-8"
)
)
- backup = _commit_workflow_file(staged, target_path, existed_before)
+ backup = cli._commit_workflow_file(staged, target_path, existed_before)
except BaseException:
- _safe_discard_staged_workflow_file(
+ cli._safe_discard_staged_workflow_file(
staged, target_path.parent, existed_before
)
raise
except OSError as exc:
err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")
return None
- _discard_committed_backup_file(backup)
+ cli._discard_committed_backup_file(backup)
console.print(
f"[green]\u2713[/green] Overlay '{overlay.id}' added for workflow '{overlay.extends}'"
@@ -294,7 +287,7 @@ def _update_overlay_field(
value: Any,
) -> bool:
"""Update a single field in a project-local overlay file."""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
path = _find_overlay_file(project_root, workflow_id, overlay_id)
if path is None:
err_console.print(
@@ -319,7 +312,7 @@ def _update_overlay_field(
backup: Path | None = None
try:
existed_before = path.exists()
- staged = _stage_workflow_file(path.parent)
+ staged = cli._stage_workflow_file(path.parent)
try:
# ``allow_unicode=True`` matches every other YAML writer in the
# repo. Without it every non-ASCII character in a hand-authored
@@ -330,14 +323,16 @@ def _update_overlay_field(
"utf-8"
)
)
- backup = _commit_workflow_file(staged, path, existed_before)
+ backup = cli._commit_workflow_file(staged, path, existed_before)
except BaseException:
- _safe_discard_staged_workflow_file(staged, path.parent, existed_before)
+ cli._safe_discard_staged_workflow_file(
+ staged, path.parent, existed_before
+ )
raise
except OSError as exc:
err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")
return False
- _discard_committed_backup_file(backup)
+ cli._discard_committed_backup_file(backup)
return True
@@ -393,7 +388,7 @@ def workflow_overlay_remove(
overlay_id: str,
) -> bool:
"""Remove a project-local overlay file."""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
path = _find_overlay_file(project_root, workflow_id, overlay_id)
if path is None:
err_console.print(
@@ -416,7 +411,7 @@ def workflow_overlay_list(project_root: Path, workflow_id: str) -> list[dict[str
Returns the raw list data for machine-readable callers, or None on error.
"""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
_validate_workflow_id_or_exit(workflow_id)
resolver = WorkflowResolver(project_root)
try:
@@ -455,7 +450,7 @@ def workflow_resolve(project_root: Path, workflow_id: str) -> dict[str, Any] | N
Returns a serializable attribution payload.
"""
- _reject_unsafe_workflow_storage(project_root)
+ cli._reject_unsafe_workflow_storage(project_root)
_validate_workflow_id_or_exit(workflow_id)
resolver = WorkflowResolver(project_root)
try:
diff --git a/src/specify_cli/workflows/overlays/__init__.py b/src/specify_cli/workflows/overlay/resolver.py
similarity index 97%
rename from src/specify_cli/workflows/overlays/__init__.py
rename to src/specify_cli/workflows/overlay/resolver.py
index 2bb87ffbe..bd50de6da 100644
--- a/src/specify_cli/workflows/overlays/__init__.py
+++ b/src/specify_cli/workflows/overlay/resolver.py
@@ -1,4 +1,4 @@
-"""Workflow overlay resolver — composes installed workflows from layers."""
+"""Workflow overlay resolver."""
from __future__ import annotations
diff --git a/src/specify_cli/workflows/overlays/schema.py b/src/specify_cli/workflows/overlay/schema.py
similarity index 100%
rename from src/specify_cli/workflows/overlays/schema.py
rename to src/specify_cli/workflows/overlay/schema.py
diff --git a/src/specify_cli/workflows/step/__init__.py b/src/specify_cli/workflows/step/__init__.py
new file mode 100644
index 000000000..39669343b
--- /dev/null
+++ b/src/specify_cli/workflows/step/__init__.py
@@ -0,0 +1,28 @@
+"""Registration for the nested ``specify workflow step`` command group."""
+
+from __future__ import annotations
+
+import typer
+
+step_app = typer.Typer(
+ name="step",
+ help="Manage workflow step types",
+ add_completion=False,
+)
+
+
+def register(app: typer.Typer) -> None:
+ """Attach the step command group to the workflow app."""
+ from .catalog import register as register_catalog
+
+ register_catalog(step_app)
+
+ # isort: off
+ 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_search # noqa: F401 -- registers handler
+ from . import command_info # noqa: F401 -- registers handler
+ # isort: on
+
+ app.add_typer(step_app, name="step")
diff --git a/src/specify_cli/workflows/step/_helpers.py b/src/specify_cli/workflows/step/_helpers.py
new file mode 100644
index 000000000..45250ceff
--- /dev/null
+++ b/src/specify_cli/workflows/step/_helpers.py
@@ -0,0 +1,107 @@
+"""Shared validation helpers for workflow step commands."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+
+# Custom step packages contain executable Python, metadata, and optional helper
+# files downloaded one-by-one rather than as an archive. Mirror the archive
+# ceilings so a catalog cannot turn individually valid files into an unbounded
+# aggregate download.
+_MAX_STEP_PACKAGE_FILES = 512
+_MAX_STEP_PACKAGE_BYTES = 50 * 1024 * 1024 # 50 MiB
+
+_RESERVED_STEP_IDS: frozenset[str] = frozenset({".cache", "step-registry.json"})
+
+_WINDOWS_RESERVED_NAMES: frozenset[str] = frozenset(
+ {
+ "con",
+ "prn",
+ "aux",
+ "nul",
+ "com1",
+ "com2",
+ "com3",
+ "com4",
+ "com5",
+ "com6",
+ "com7",
+ "com8",
+ "com9",
+ "lpt1",
+ "lpt2",
+ "lpt3",
+ "lpt4",
+ "lpt5",
+ "lpt6",
+ "lpt7",
+ "lpt8",
+ "lpt9",
+ }
+)
+
+_WINDOWS_INVALID_CHARS: frozenset[str] = frozenset('<>:"|?*')
+
+
+def _validate_step_id_or_exit(step_id: str) -> None:
+ """Validate that ``step_id`` is a single safe path component.
+
+ Rejects empty strings, whitespace-only strings, leading/trailing whitespace,
+ path separators, ``.``/``..`` components, dotfile prefixes, reserved names,
+ Windows-invalid filename characters, trailing dots/spaces, and Windows
+ reserved device names. Exits with code 1 on failure.
+ """
+ # Strip the stem (before first dot) for Windows reserved-name check
+ stem = step_id.split(".")[0].lower() if step_id else ""
+ if (
+ not step_id
+ or not step_id.strip()
+ or step_id != step_id.strip()
+ or "/" in step_id
+ or "\\" in step_id
+ or step_id in (".", "..")
+ or step_id.startswith(".")
+ or step_id.endswith(".")
+ or step_id.endswith(" ")
+ or step_id.lower() in _RESERVED_STEP_IDS
+ or stem in _WINDOWS_RESERVED_NAMES
+ or any(c in _WINDOWS_INVALID_CHARS for c in step_id)
+ or any(ord(c) < 32 for c in step_id)
+ ):
+ cli.console.print(
+ f"[red]Error:[/red] Invalid step id '{step_id}': must be a single safe "
+ "path component (no separators, no leading dot, not a reserved name, "
+ "no invalid filename characters)"
+ )
+ raise cli.typer.Exit(1)
+
+
+def _resolve_steps_base_dir_or_exit(project_root: cli.Path) -> cli.Path:
+ """Resolve .specify/workflows/steps while refusing symlinked parent directories."""
+ project_root_resolved = project_root.resolve()
+ steps_base_dir_unresolved = project_root / ".specify" / "workflows" / "steps"
+
+ current = project_root
+ for part in (".specify", "workflows", "steps"):
+ current = current / part
+ if current.is_symlink():
+ cli.console.print(
+ f"[red]Error:[/red] Refusing to use symlinked step directory '{current}'"
+ )
+ raise cli.typer.Exit(1)
+ if current.exists() and not current.is_dir():
+ cli.console.print(
+ f"[red]Error:[/red] Step directory path is not a directory: '{current}'"
+ )
+ raise cli.typer.Exit(1)
+
+ steps_base_dir = steps_base_dir_unresolved.resolve()
+ try:
+ steps_base_dir.relative_to(project_root_resolved)
+ except ValueError:
+ cli.console.print(
+ f"[red]Error:[/red] Step directory escapes project root: '{steps_base_dir}'"
+ )
+ raise cli.typer.Exit(1)
+
+ return steps_base_dir
diff --git a/src/specify_cli/workflows/step/catalog/__init__.py b/src/specify_cli/workflows/step/catalog/__init__.py
new file mode 100644
index 000000000..da783f45e
--- /dev/null
+++ b/src/specify_cli/workflows/step/catalog/__init__.py
@@ -0,0 +1,48 @@
+"""Step catalog domain API and nested CLI registration."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+import typer
+
+from ...._download_security import MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES
+
+catalog_app = typer.Typer(
+ name="catalog",
+ help="Manage step catalogs",
+ add_completion=False,
+)
+
+
+def register(app: typer.Typer) -> None:
+ """Attach the step catalog group to the step app."""
+ from . import command_list # noqa: F401 -- registers handler
+ from . import command_add # noqa: F401 -- registers handler
+ from . import command_remove # noqa: F401 -- registers handler
+
+ app.add_typer(catalog_app, name="catalog")
+
+
+_DOMAIN_EXPORTS = {
+ "StepCatalog",
+ "StepCatalogEntry",
+ "StepCatalogError",
+ "StepRegistry",
+ "StepValidationError",
+}
+_COMPATIBILITY_EXPORTS = {"json", "os"}
+
+
+def __getattr__(name: str) -> Any:
+ """Load step catalog domain symbols only when requested."""
+ if name not in _DOMAIN_EXPORTS | _COMPATIBILITY_EXPORTS:
+ raise AttributeError(name)
+ domain = import_module(f"{__name__}._domain")
+ value = getattr(domain, name)
+ globals()[name] = value
+ return value
+
+
+__all__ = sorted(_DOMAIN_EXPORTS)
diff --git a/src/specify_cli/workflows/step/catalog/_domain.py b/src/specify_cli/workflows/step/catalog/_domain.py
new file mode 100644
index 000000000..cebebb3e2
--- /dev/null
+++ b/src/specify_cli/workflows/step/catalog/_domain.py
@@ -0,0 +1,710 @@
+"""Step catalog discovery, installation, and registry domain API."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ...._download_security import (
+ MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES,
+ read_response_limited,
+)
+
+
+def _max_json_catalog_bytes() -> int:
+ """Read the step-catalog compatibility size limit at call time."""
+ from . import MAX_JSON_CATALOG_BYTES as configured_limit
+
+ return configured_limit
+
+
+# ---------------------------------------------------------------------------
+# Step catalog errors
+# ---------------------------------------------------------------------------
+
+
+class StepCatalogError(Exception):
+ """Base error for step catalog operations."""
+
+
+class StepValidationError(StepCatalogError):
+ """Validation error for step catalog config or step data."""
+
+
+# ---------------------------------------------------------------------------
+# StepCatalogEntry
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StepCatalogEntry:
+ """Represents a single step catalog source in the catalog stack."""
+
+ url: str
+ name: str
+ priority: int
+ install_allowed: bool
+ description: str = ""
+
+
+# ---------------------------------------------------------------------------
+# StepRegistry
+# ---------------------------------------------------------------------------
+
+
+class StepRegistry:
+ """Manages the registry of installed custom step types.
+
+ Tracks installed step types and their metadata in
+ ``.specify/workflows/steps/step-registry.json``.
+ """
+
+ REGISTRY_FILE = "step-registry.json"
+ SCHEMA_VERSION = "1.0"
+
+ def __init__(self, project_root: Path) -> None:
+ self.project_root = project_root
+ self.steps_dir = project_root / ".specify" / "workflows" / "steps"
+ self.registry_path = self.steps_dir / self.REGISTRY_FILE
+ self.data = self._load()
+
+ def _has_symlinked_parent(self) -> bool:
+ """Return True if any directory under .specify/workflows/steps is a symlink."""
+ current = self.project_root
+ for part in (".specify", "workflows", "steps"):
+ current = current / part
+ if current.is_symlink():
+ return True
+ return False
+
+ def _load(self) -> dict[str, Any]:
+ """Load registry from disk or create default."""
+ default_registry: dict[str, Any] = {"schema_version": self.SCHEMA_VERSION, "steps": {}}
+ # Defense-in-depth: refuse to read the registry if any parent directory
+ # under .specify/workflows/steps is a symlink, which could redirect the
+ # read outside the project root.
+ if self._has_symlinked_parent():
+ return default_registry
+ # Defense-in-depth: also refuse to read a symlinked registry file,
+ # which could redirect the read outside the project root.
+ if self.registry_path.is_symlink():
+ return default_registry
+ if self.registry_path.exists():
+ try:
+ with open(self.registry_path, encoding="utf-8") as f:
+ data = json.load(f)
+ # Validate shape: must be a dict with a dict "steps" field
+ if not isinstance(data, dict):
+ return default_registry
+ if not isinstance(data.get("steps"), dict):
+ data["steps"] = {}
+ return data
+ except (json.JSONDecodeError, ValueError, OSError, UnicodeError):
+ return default_registry
+ return default_registry
+
+ def save(self) -> None:
+ """Persist registry to disk.
+
+ Raises ``StepValidationError`` with a clear message on filesystem
+ errors (read-only fs, permission denied, ...) so callers can surface
+ a clean error to the user rather than an unhandled ``OSError``.
+ """
+ if self._has_symlinked_parent() or self.registry_path.is_symlink():
+ raise StepValidationError(
+ "Refusing to write step registry through a symlinked path."
+ )
+ try:
+ self.steps_dir.mkdir(parents=True, exist_ok=True)
+ with open(self.registry_path, "w", encoding="utf-8") as f:
+ json.dump(self.data, f, indent=2)
+ except OSError as exc:
+ raise StepValidationError(
+ f"Failed to write step registry at {self.registry_path}: {exc}"
+ ) from exc
+
+ def add(self, step_id: str, metadata: dict[str, Any]) -> None:
+ """Add or update an installed step entry."""
+ import copy
+ from datetime import datetime, timezone
+
+ raw_existing = self.data["steps"].get(step_id)
+ # Corrupted-but-parseable registries may hold non-dict entries; treat
+ # them as absent rather than crashing on existing.get() (mirrors
+ # WorkflowRegistry.add).
+ existing = raw_existing if isinstance(raw_existing, dict) else {}
+ metadata_to_store = copy.deepcopy(metadata)
+ metadata_to_store["installed_at"] = existing.get(
+ "installed_at", datetime.now(timezone.utc).isoformat()
+ )
+ metadata_to_store["updated_at"] = datetime.now(timezone.utc).isoformat()
+ self.data["steps"][step_id] = metadata_to_store
+ self.save()
+
+ def remove(self, step_id: str) -> bool:
+ """Remove an installed step entry. Returns True if found."""
+ if step_id in self.data["steps"]:
+ del self.data["steps"][step_id]
+ self.save()
+ return True
+ return False
+
+ def get(self, step_id: str) -> dict[str, Any] | None:
+ """Get metadata for an installed step."""
+ return self.data["steps"].get(step_id)
+
+ def list(self) -> dict[str, dict[str, Any]]:
+ """Return all installed steps."""
+ return dict(self.data["steps"])
+
+ def is_installed(self, step_id: str) -> bool:
+ """Check if a step is installed."""
+ return step_id in self.data["steps"]
+
+
+# ---------------------------------------------------------------------------
+# StepCatalog
+# ---------------------------------------------------------------------------
+
+
+class StepCatalog:
+ """Manages step catalog fetching, caching, and searching.
+
+ Resolution order for catalog sources:
+ 1. ``SPECKIT_STEP_CATALOG_URL`` env var (overrides all)
+ 2. Project-level ``.specify/step-catalogs.yml``
+ 3. User-level ``~/.specify/step-catalogs.yml``
+ 4. Built-in defaults (official + community)
+ """
+
+ DEFAULT_CATALOG_URL = (
+ "https://raw.githubusercontent.com/github/spec-kit/main/"
+ "workflows/step-catalog.json"
+ )
+ COMMUNITY_CATALOG_URL = (
+ "https://raw.githubusercontent.com/github/spec-kit/main/"
+ "workflows/step-catalog.community.json"
+ )
+ CACHE_DURATION = 3600 # 1 hour
+
+ def __init__(self, project_root: Path) -> None:
+ self.project_root = project_root
+ self.steps_dir = project_root / ".specify" / "workflows" / "steps"
+ self.cache_dir = self.steps_dir / ".cache"
+
+ def _is_cache_path_safe(self) -> bool:
+ """Return False if any component of the cache path is a symlink."""
+ current = self.project_root
+ for part in (".specify", "workflows", "steps", ".cache"):
+ current = current / part
+ if current.is_symlink():
+ return False
+ return True
+
+ # -- Catalog resolution -----------------------------------------------
+
+ def _validate_catalog_url(self, url: str) -> None:
+ """Validate that a catalog URL uses HTTPS (localhost HTTP allowed)."""
+ from urllib.parse import urlparse
+
+ # A malformed authority (e.g. an unterminated IPv6 bracket
+ # "https://[::1") makes urlparse / hostname access raise ValueError.
+ # This validator's contract is to raise StepValidationError for a bad
+ # URL, so surface that rather than leaking a raw ValueError past the
+ # command handler (which only catches StepValidationError). Mirrors
+ # specify_cli.catalogs (#3435).
+ try:
+ parsed = urlparse(url)
+ hostname = parsed.hostname
+ _ = parsed.port
+ except (TypeError, ValueError):
+ raise StepValidationError(
+ f"Catalog URL is malformed: {url}"
+ ) from None
+ is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (
+ parsed.scheme == "http" and is_localhost
+ ):
+ raise StepValidationError(
+ f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
+ "HTTP is only allowed for localhost."
+ )
+ if not hostname:
+ raise StepValidationError(
+ "Catalog URL must be a valid URL with a host."
+ )
+
+ def _load_catalog_config(
+ self, config_path: Path
+ ) -> list[StepCatalogEntry] | None:
+ """Load catalog stack configuration from a YAML file."""
+ if not config_path.exists():
+ return None
+ try:
+ data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ except (yaml.YAMLError, OSError, UnicodeError) as exc:
+ raise StepValidationError(
+ f"Failed to read catalog config {config_path}: {exc}"
+ ) from exc
+ # Same two guards as WorkflowCatalog._load_catalog_config above, kept in
+ # lockstep: this is the step-catalog twin of that loader and read the
+ # same way. Dropping ``or {}`` stops a falsy non-mapping top level from
+ # being coerced past the isinstance check, and the ``catalogs`` shape
+ # check runs before the emptiness check for the same reason.
+ if data is None:
+ return None
+ if not isinstance(data, dict):
+ raise StepValidationError(
+ f"Invalid catalog config: expected a mapping, "
+ f"got {type(data).__name__}"
+ )
+ catalogs_data = data.get("catalogs")
+ if catalogs_data is None:
+ return None
+ if not isinstance(catalogs_data, list):
+ raise StepValidationError(
+ f"Invalid catalog config: 'catalogs' must be a list, "
+ f"got {type(catalogs_data).__name__}"
+ )
+ if not catalogs_data:
+ return None
+
+ entries: list[StepCatalogEntry] = []
+ for idx, item in enumerate(catalogs_data):
+ if not isinstance(item, dict):
+ raise StepValidationError(
+ f"Invalid catalog entry at index {idx}: "
+ f"expected a mapping, got {type(item).__name__}"
+ )
+ url = str(item.get("url", "")).strip()
+ if not url:
+ continue
+ self._validate_catalog_url(url)
+ raw_priority = item.get("priority", idx + 1)
+ # bool is an int subclass: reject ``priority: true`` explicitly rather
+ # than silently coercing it to 1 (mirrors CatalogStackBase).
+ if isinstance(raw_priority, bool):
+ raise StepValidationError(
+ f"Invalid priority for catalog "
+ f"'{item.get('name', idx + 1)}': "
+ f"expected integer, got {raw_priority!r}"
+ )
+ try:
+ priority = int(raw_priority)
+ except (TypeError, ValueError, OverflowError):
+ # OverflowError: int(float("inf")) — a ``priority: .inf``.
+ raise StepValidationError(
+ f"Invalid priority for catalog "
+ f"'{item.get('name', idx + 1)}': "
+ f"expected integer, got {raw_priority!r}"
+ )
+ raw_install = item.get("install_allowed", False)
+ if isinstance(raw_install, str):
+ install_allowed = raw_install.strip().lower() in (
+ "true",
+ "yes",
+ "1",
+ )
+ else:
+ install_allowed = bool(raw_install)
+ entries.append(
+ StepCatalogEntry(
+ url=url,
+ name=str(item.get("name", f"catalog-{idx + 1}")),
+ priority=priority,
+ install_allowed=install_allowed,
+ description=str(item.get("description", "")),
+ )
+ )
+ entries.sort(key=lambda e: e.priority)
+ if not entries:
+ raise StepValidationError(
+ f"Catalog config {config_path} contains {len(catalogs_data)} "
+ f"entries but none have valid URLs."
+ )
+ return entries
+
+ def get_active_catalogs(self) -> list[StepCatalogEntry]:
+ """Get the ordered list of active step catalogs."""
+ # 1. Environment variable override
+ env_url = os.environ.get("SPECKIT_STEP_CATALOG_URL", "").strip()
+ if env_url:
+ self._validate_catalog_url(env_url)
+ return [
+ StepCatalogEntry(
+ url=env_url,
+ name="env-override",
+ priority=1,
+ install_allowed=True,
+ description="From SPECKIT_STEP_CATALOG_URL",
+ )
+ ]
+
+ # 2. Project-level config
+ project_config = self.project_root / ".specify" / "step-catalogs.yml"
+ project_entries = self._load_catalog_config(project_config)
+ if project_entries is not None:
+ return project_entries
+
+ # 3. User-level config
+ home = Path.home()
+ user_config = home / ".specify" / "step-catalogs.yml"
+ user_entries = self._load_catalog_config(user_config)
+ if user_entries is not None:
+ return user_entries
+
+ # 4. Built-in defaults
+ return [
+ StepCatalogEntry(
+ url=self.DEFAULT_CATALOG_URL,
+ name="default",
+ priority=1,
+ install_allowed=True,
+ description="Official step types",
+ ),
+ StepCatalogEntry(
+ url=self.COMMUNITY_CATALOG_URL,
+ name="community",
+ priority=2,
+ install_allowed=False,
+ description="Community-contributed step types (discovery only)",
+ ),
+ ]
+
+ # -- Caching ----------------------------------------------------------
+
+ def _get_cache_paths(self, url: str) -> tuple[Path, Path]:
+ """Get cache file paths for a URL (hash-based)."""
+ url_hash = hashlib.sha256(url.encode()).hexdigest()[:16]
+ cache_file = self.cache_dir / f"step-catalog-{url_hash}.json"
+ meta_file = self.cache_dir / f"step-catalog-{url_hash}-meta.json"
+ return cache_file, meta_file
+
+ def _is_url_cache_valid(self, url: str) -> bool:
+ """Check if cached data for a URL is still fresh."""
+ _, meta_file = self._get_cache_paths(url)
+ if not meta_file.exists():
+ return False
+ try:
+ with open(meta_file, encoding="utf-8") as f:
+ meta = json.load(f)
+ if not isinstance(meta, dict):
+ return False
+ fetched_at = float(meta.get("fetched_at", 0))
+ return (time.time() - fetched_at) < self.CACHE_DURATION
+ except (json.JSONDecodeError, OSError, TypeError, ValueError):
+ return False
+
+ def _fetch_single_catalog(
+ self, entry: StepCatalogEntry, force_refresh: bool = False
+ ) -> dict[str, Any]:
+ """Fetch a single catalog, using cache when possible."""
+ cache_safe = self._is_cache_path_safe()
+ cache_file, meta_file = self._get_cache_paths(entry.url)
+
+ if cache_safe and not force_refresh and self._is_url_cache_valid(entry.url):
+ try:
+ with open(cache_file, encoding="utf-8") as f:
+ cached = json.load(f)
+ if isinstance(cached, dict):
+ return cached
+ except (UnicodeDecodeError, json.JSONDecodeError, OSError):
+ # Ignore invalid/unreadable cache and fall back to fetching from source.
+ pass
+
+ from urllib.parse import urlparse
+ from specify_cli.authentication.http import open_url as _open_url
+
+ def _validate_url(url: str) -> None:
+ # A malformed authority (e.g. "https://[::1") makes urlparse /
+ # hostname access raise ValueError; treat it as a refused fetch
+ # rather than leaking a raw ValueError (this also validates the
+ # post-redirect resp.geturl(), so a hostile redirect target cannot
+ # crash the fetch either).
+ try:
+ parsed = urlparse(url)
+ hostname = parsed.hostname
+ _ = parsed.port
+ except (TypeError, ValueError):
+ raise StepCatalogError(
+ f"Refusing to fetch catalog from malformed URL: {url}"
+ ) from None
+ is_localhost = hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (
+ parsed.scheme == "http" and is_localhost
+ ):
+ raise StepCatalogError(
+ f"Refusing to fetch catalog from non-HTTPS URL: {url}"
+ )
+ if not hostname:
+ raise StepCatalogError(
+ f"Refusing to fetch catalog from URL with no hostname: {url}"
+ )
+
+ _validate_url(entry.url)
+
+ # Validate EVERY redirect hop, not just the final URL: _open_url follows
+ # redirects, so an https:// entry that 30x-redirects through http:// (or
+ # to a non-HTTPS host mid-chain) could otherwise let a network attacker
+ # rewrite the next hop and slip a payload past a final-URL-only check.
+ # redirect_validator runs before each hop; the geturl() check below is
+ # retained as a defense-in-depth backstop. Mirrors the presets/extensions
+ # catalog fix (#3523 / #3524).
+ def _validate_redirect(_old_url: str, new_url: str) -> None:
+ _validate_url(new_url)
+
+ try:
+ with _open_url(
+ entry.url, timeout=30, redirect_validator=_validate_redirect
+ ) as resp:
+ _validate_url(resp.geturl())
+ data = json.loads(
+ read_response_limited(
+ resp,
+ max_bytes=_max_json_catalog_bytes(),
+ error_type=StepCatalogError,
+ label="step catalog",
+ ).decode("utf-8")
+ )
+ except Exception as exc:
+ if cache_safe and cache_file.exists():
+ try:
+ with open(cache_file, encoding="utf-8") as f:
+ cached = json.load(f)
+ if isinstance(cached, dict):
+ return cached
+ except (json.JSONDecodeError, ValueError, OSError):
+ # Stale-cache read failed; let the original fetch error propagate.
+ pass
+ raise StepCatalogError(
+ f"Failed to fetch catalog from {entry.url}: {exc}"
+ ) from exc
+
+ if not isinstance(data, dict):
+ raise StepCatalogError(
+ f"Catalog from {entry.url} is not a valid JSON object."
+ )
+
+ if cache_safe:
+ try:
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
+ with open(cache_file, "w", encoding="utf-8") as f:
+ json.dump(data, f, indent=2)
+ with open(meta_file, "w", encoding="utf-8") as f:
+ json.dump({"url": entry.url, "fetched_at": time.time()}, f)
+ except OSError:
+ pass # Proceed without caching if disk write fails
+
+ return data
+
+ def _get_merged_steps(
+ self, force_refresh: bool = False
+ ) -> dict[str, dict[str, Any]]:
+ """Merge steps from all active catalogs (lower priority number wins)."""
+ catalogs = self.get_active_catalogs()
+ merged: dict[str, dict[str, Any]] = {}
+ fetch_errors = 0
+
+ for entry in reversed(catalogs):
+ try:
+ data = self._fetch_single_catalog(entry, force_refresh)
+ except StepCatalogError:
+ fetch_errors += 1
+ continue
+ steps = data.get("steps", {})
+ if isinstance(steps, dict):
+ for step_id, step_data in steps.items():
+ if not isinstance(step_data, dict):
+ continue
+ step_data["_catalog_name"] = entry.name
+ step_data["_install_allowed"] = entry.install_allowed
+ merged[step_id] = step_data
+ elif isinstance(steps, list):
+ for step_data in steps:
+ if not isinstance(step_data, dict):
+ continue
+ raw_step_id = step_data.get("id")
+ if raw_step_id is None:
+ continue
+ step_id = str(raw_step_id).strip()
+ if step_id:
+ step_data["id"] = step_id
+ step_data["_catalog_name"] = entry.name
+ step_data["_install_allowed"] = entry.install_allowed
+ merged[step_id] = step_data
+ if fetch_errors == len(catalogs) and catalogs:
+ raise StepCatalogError("All configured step catalogs failed to fetch.")
+ return merged
+
+ # -- Public API -------------------------------------------------------
+
+ def search(
+ self,
+ query: str | None = None,
+ ) -> list[dict[str, Any]]:
+ """Search step types across all configured catalogs."""
+ merged = self._get_merged_steps()
+ results: list[dict[str, Any]] = []
+
+ for step_id, step_data in merged.items():
+ step_data.setdefault("id", step_id)
+ if query:
+ q = query.lower()
+ searchable = " ".join(
+ [
+ str(step_data.get("name") or ""),
+ str(step_data.get("description") or ""),
+ str(step_data.get("id") or ""),
+ ]
+ ).lower()
+ if q not in searchable:
+ continue
+ results.append(step_data)
+ return results
+
+ def get_step_info(self, step_id: str) -> dict[str, Any] | None:
+ """Get details for a specific step from the catalog."""
+ merged = self._get_merged_steps()
+ step = merged.get(step_id)
+ if step:
+ step.setdefault("id", step_id)
+ return step
+
+ def get_catalog_configs(self) -> list[dict[str, Any]]:
+ """Return current catalog configuration as a list of dicts."""
+ entries = self.get_active_catalogs()
+ return [
+ {
+ "name": e.name,
+ "url": e.url,
+ "priority": e.priority,
+ "install_allowed": e.install_allowed,
+ "description": e.description,
+ }
+ for e in entries
+ ]
+
+ def add_catalog(self, url: str, name: str | None = None) -> None:
+ """Add a catalog source to the project-level config."""
+ self._validate_catalog_url(url)
+ config_path = self.project_root / ".specify" / "step-catalogs.yml"
+
+ data: dict[str, Any] = {"catalogs": []}
+ if config_path.exists():
+ try:
+ raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise StepValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
+ if raw is None:
+ raw = {}
+ elif not isinstance(raw, dict):
+ raise StepValidationError(
+ "Catalog config file is corrupted (expected a mapping)."
+ )
+ data = raw
+
+ catalogs = data.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ raise StepValidationError(
+ "Catalog config 'catalogs' must be a list."
+ )
+ for cat in catalogs:
+ if isinstance(cat, dict) and cat.get("url") == url:
+ raise StepValidationError(
+ f"Catalog URL already configured: {url}"
+ )
+
+ # Coerce existing priorities to int with a safe fallback so a user-edited
+ # step-catalogs.yml with a non-integer priority (e.g. "1") doesn't blow up.
+ def _coerce_priority(value: Any) -> int:
+ try:
+ return int(value)
+ except (TypeError, ValueError, OverflowError):
+ # OverflowError: int(float("inf")) — treat an uncoercible
+ # existing priority as 0 rather than crashing 'catalog add'.
+ return 0
+
+ max_priority = max(
+ (
+ _coerce_priority(cat.get("priority", 0))
+ for cat in catalogs
+ if isinstance(cat, dict)
+ ),
+ default=0,
+ )
+ catalogs.append(
+ {
+ "name": name or f"catalog-{len(catalogs) + 1}",
+ "url": url,
+ "priority": max_priority + 1,
+ "install_allowed": True,
+ "description": "",
+ }
+ )
+ data["catalogs"] = catalogs
+
+ try:
+ config_path.parent.mkdir(parents=True, exist_ok=True)
+ with open(config_path, "w", encoding="utf-8") as f:
+ yaml.dump(
+ data, f, default_flow_style=False, sort_keys=False, allow_unicode=True
+ )
+ except OSError as exc:
+ raise StepValidationError(
+ f"Failed to write catalog config {config_path}: {exc}"
+ ) from exc
+
+ def remove_catalog(self, index: int) -> str:
+ """Remove a catalog source by index (0-based). Returns the removed name."""
+ config_path = self.project_root / ".specify" / "step-catalogs.yml"
+ if not config_path.exists():
+ raise StepValidationError("No step catalog config file found.")
+
+ try:
+ data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise StepValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
+ if data is None:
+ data = {}
+ elif not isinstance(data, dict):
+ raise StepValidationError(
+ "Catalog config file is corrupted (expected a mapping)."
+ )
+ catalogs = data.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ raise StepValidationError(
+ "Catalog config 'catalogs' must be a list."
+ )
+
+ if index < 0 or index >= len(catalogs):
+ raise StepValidationError(
+ f"Catalog index {index} out of range (0-{len(catalogs) - 1})."
+ )
+
+ removed = catalogs.pop(index)
+ data["catalogs"] = catalogs
+
+ try:
+ with open(config_path, "w", encoding="utf-8") as f:
+ yaml.dump(
+ data, f, default_flow_style=False, sort_keys=False, allow_unicode=True
+ )
+ except OSError as exc:
+ raise StepValidationError(
+ f"Failed to write catalog config {config_path}: {exc}"
+ ) from exc
+
+ if isinstance(removed, dict):
+ return removed.get("name", f"catalog-{index + 1}")
+ return f"catalog-{index + 1}"
diff --git a/src/specify_cli/workflows/step/catalog/command_add.py b/src/specify_cli/workflows/step/catalog/command_add.py
new file mode 100644
index 000000000..845473c7a
--- /dev/null
+++ b/src/specify_cli/workflows/step/catalog/command_add.py
@@ -0,0 +1,26 @@
+"""Command handler for ``specify workflow step catalog add``."""
+
+from __future__ import annotations
+
+from ... import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("add")
+def workflow_step_catalog_add(
+ url: str = cli.typer.Argument(..., help="Catalog URL to add"),
+ name: str | None = cli.typer.Option(None, "--name", help="Catalog name"),
+):
+ """Add a step catalog source."""
+ from . import StepCatalog, StepValidationError
+
+ project_root = cli._require_specify_project()
+
+ catalog = StepCatalog(project_root)
+ try:
+ catalog.add_catalog(url, name)
+ except StepValidationError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Step catalog source added: {url}")
diff --git a/src/specify_cli/workflows/step/catalog/command_list.py b/src/specify_cli/workflows/step/catalog/command_list.py
new file mode 100644
index 000000000..2addd0579
--- /dev/null
+++ b/src/specify_cli/workflows/step/catalog/command_list.py
@@ -0,0 +1,38 @@
+"""Command handler for ``specify workflow step catalog list``."""
+
+from __future__ import annotations
+
+from ... import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("list")
+def workflow_step_catalog_list():
+ """List configured step catalog sources."""
+ from . import StepCatalog, StepCatalogError
+
+ project_root = cli._require_specify_project()
+ catalog = StepCatalog(project_root)
+
+ try:
+ configs = catalog.get_catalog_configs()
+ except StepCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print("\n[bold cyan]Step Catalog Sources:[/bold cyan]\n")
+ for i, cfg in enumerate(configs):
+ install_status = (
+ "[green]install allowed[/green]"
+ if cfg["install_allowed"]
+ else "[yellow]discovery only[/yellow]"
+ )
+ cli.console.print(
+ f" [{i}] [bold]{cli._escape_markup(str(cfg['name']))}[/bold] — {install_status}"
+ )
+ cli.console.print(f" {cli._escape_markup(str(cfg['url']))}")
+ if cfg.get("description"):
+ cli.console.print(
+ f" [dim]{cli._escape_markup(str(cfg['description']))}[/dim]"
+ )
+ cli.console.print()
diff --git a/src/specify_cli/workflows/step/catalog/command_remove.py b/src/specify_cli/workflows/step/catalog/command_remove.py
new file mode 100644
index 000000000..6eba4f853
--- /dev/null
+++ b/src/specify_cli/workflows/step/catalog/command_remove.py
@@ -0,0 +1,27 @@
+"""Command handler for ``specify workflow step catalog remove``."""
+
+from __future__ import annotations
+
+from ... import _commands as cli
+from . import catalog_app
+
+
+@catalog_app.command("remove")
+def workflow_step_catalog_remove(
+ index: int = cli.typer.Argument(
+ ..., help="Catalog index to remove (from 'step catalog list')"
+ ),
+):
+ """Remove a step catalog source by index."""
+ from . import StepCatalog, StepValidationError
+
+ project_root = cli._require_specify_project()
+
+ catalog = StepCatalog(project_root)
+ try:
+ removed_name = catalog.remove_catalog(index)
+ except StepValidationError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Step catalog source '{removed_name}' removed")
diff --git a/src/specify_cli/workflows/steps/command/__init__.py b/src/specify_cli/workflows/step/command/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/command/__init__.py
rename to src/specify_cli/workflows/step/command/__init__.py
diff --git a/src/specify_cli/workflows/step/command_add.py b/src/specify_cli/workflows/step/command_add.py
new file mode 100644
index 000000000..7a3a3b8ca
--- /dev/null
+++ b/src/specify_cli/workflows/step/command_add.py
@@ -0,0 +1,376 @@
+"""Command handler for ``specify workflow step add``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import step_app
+
+from . import _helpers as step_helpers
+
+
+@step_app.command("add")
+def workflow_step_add(
+ step_id: str = cli.typer.Argument(..., help="Step type ID from catalog"),
+):
+ """Install a custom step type from the step catalog."""
+ from .catalog import (
+ StepCatalog,
+ StepCatalogError,
+ StepRegistry,
+ StepValidationError,
+ )
+
+ project_root = cli._require_specify_project()
+
+ catalog = StepCatalog(project_root)
+ try:
+ info = catalog.get_step_info(step_id)
+ except StepCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ if not info:
+ cli.console.print(
+ f"[red]Error:[/red] Step type '{step_id}' not found in catalog"
+ )
+ raise cli.typer.Exit(1)
+
+ if not info.get("_install_allowed", True):
+ cli.console.print(
+ f"[yellow]Warning:[/yellow] Step type '{step_id}' is from a discovery-only catalog"
+ )
+ cli.console.print("Direct installation is not enabled for this catalog source.")
+ raise cli.typer.Exit(1)
+
+ # Reject step IDs that collide with built-in step types
+ from .. import STEP_REGISTRY as _step_reg
+
+ if step_id in _step_reg:
+ cli.console.print(
+ f"[red]Error:[/red] Step type '{step_id}' conflicts with a built-in step type"
+ )
+ raise cli.typer.Exit(1)
+
+ # Reject if already installed
+ registry = StepRegistry(project_root)
+ if registry.is_installed(step_id):
+ cli.console.print(
+ f"[red]Error:[/red] Step type '{step_id}' is already installed. "
+ "Remove it first with: [cyan]specify workflow step remove "
+ f"{step_id}[/cyan]"
+ )
+ raise cli.typer.Exit(1)
+
+ declared_step_yml_url = info.get("step_yml_url")
+ if declared_step_yml_url is not None and not isinstance(declared_step_yml_url, str):
+ cli.console.print(
+ f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
+ "step.yml URL; expected a non-empty string"
+ )
+ raise cli.typer.Exit(1)
+ step_yml_url = declared_step_yml_url or info.get("url")
+ if step_yml_url is None or (
+ isinstance(step_yml_url, str) and not step_yml_url.strip()
+ ):
+ cli.console.print(f"[red]Error:[/red] Catalog entry for '{step_id}' has no URL")
+ raise cli.typer.Exit(1)
+ if not isinstance(step_yml_url, str):
+ cli.console.print(
+ f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
+ "step.yml URL; expected a non-empty string"
+ )
+ raise cli.typer.Exit(1)
+
+ # Derive __init__.py URL: replace trailing step.yml with __init__.py
+ # or use explicit init_url if provided.
+ init_url = info.get("init_url")
+ if init_url is not None and (not isinstance(init_url, str) or not init_url.strip()):
+ cli.console.print(
+ f"[red]Error:[/red] Catalog entry for '{step_id}' has a malformed "
+ "__init__.py URL; expected a non-empty string"
+ )
+ raise cli.typer.Exit(1)
+ if not init_url:
+ if step_yml_url.endswith("step.yml"):
+ init_url = step_yml_url[: -len("step.yml")] + "__init__.py"
+ else:
+ cli.console.print(
+ f"[red]Error:[/red] Cannot derive __init__.py URL from '{step_yml_url}'. "
+ "Catalog entry should provide 'init_url' or a 'url' ending in 'step.yml'."
+ )
+ raise cli.typer.Exit(1)
+
+ # Preflight the declared file count before creating a staging directory or
+ # issuing any request. The two required files are always part of the package;
+ # duplicate declarations for them in extra_files are ignored below and do
+ # not count twice.
+ extra_files = info.get("extra_files")
+ if extra_files is not None and not isinstance(extra_files, dict):
+ cli.console.print(
+ "[yellow]Warning:[/yellow] Catalog entry 'extra_files' is not a mapping; "
+ "additional package files will not be downloaded."
+ )
+ extra_files = {}
+
+ def _is_required_package_file(rel_path: object) -> bool:
+ """Match portable path/case aliases of the two required package files."""
+ if not isinstance(rel_path, str):
+ return False
+ parts = cli.PurePosixPath(rel_path.replace("\\", "/")).parts
+ return len(parts) == 1 and parts[0].casefold() in {
+ "step.yml",
+ "__init__.py",
+ }
+
+ declared_extra_count = sum(
+ 1 for rel_path in (extra_files or {}) if not _is_required_package_file(rel_path)
+ )
+ package_file_count = 2 + declared_extra_count
+ if package_file_count > step_helpers._MAX_STEP_PACKAGE_FILES:
+ cli.console.print(
+ f"[red]Error:[/red] Step package declares {package_file_count} files, "
+ f"exceeding the {step_helpers._MAX_STEP_PACKAGE_FILES}-file limit"
+ )
+ raise cli.typer.Exit(1)
+
+ from specify_cli.authentication.http import open_url as _open_url
+
+ def _safe_fetch(url: str) -> bytes:
+ if not cli.is_https_or_localhost_http(url):
+ raise ValueError(f"Refusing to fetch from non-HTTPS URL: {url}")
+ with _open_url(
+ url, timeout=30, redirect_validator=cli._reject_insecure_download_redirect
+ ) as resp:
+ final_url = resp.geturl()
+ if not cli.is_https_or_localhost_http(final_url):
+ raise ValueError(f"Redirect to non-HTTPS URL: {final_url}")
+ return cli._read_response_within_limit(resp)
+
+ step_helpers._validate_step_id_or_exit(step_id)
+
+ steps_base_dir = step_helpers._resolve_steps_base_dir_or_exit(project_root)
+ step_dir = (steps_base_dir / step_id).resolve()
+ # Defense-in-depth: ensure the resolved directory is a direct child of
+ # steps_base_dir even after symlink resolution.
+ try:
+ rel_parts = step_dir.relative_to(steps_base_dir).parts
+ except ValueError:
+ cli.console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
+ raise cli.typer.Exit(1)
+ if rel_parts != (step_id,):
+ cli.console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
+ raise cli.typer.Exit(1)
+
+ import shutil
+ import tempfile
+
+ # Refuse if step_dir already exists (e.g. leftover from a previous failed/manual
+ # install that wasn't registered). The user should remove it before retrying.
+ if step_dir.exists():
+ cli.console.print(
+ f"[red]Error:[/red] Step directory already exists at '{step_dir}'. "
+ f"Remove it manually or use: [cyan]specify workflow step remove {step_id}[/cyan]"
+ )
+ raise cli.typer.Exit(1)
+
+ # Create steps_base_dir now so the staging temp dir is on the same filesystem,
+ # enabling a truly atomic os.rename() below.
+ try:
+ steps_base_dir.mkdir(parents=True, exist_ok=True)
+ tmp_path = cli.Path(
+ tempfile.mkdtemp(prefix="speckit_step_tmp_", dir=steps_base_dir)
+ )
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to create staging directory: {exc}"
+ )
+ raise cli.typer.Exit(1)
+ try:
+ try:
+ step_yml_content = _safe_fetch(step_yml_url)
+ init_py_content = _safe_fetch(init_url)
+ except Exception as exc:
+ cli.console.print(f"[red]Error:[/red] Failed to download step files: {exc}")
+ raise cli.typer.Exit(1)
+
+ package_bytes = len(step_yml_content) + len(init_py_content)
+ if package_bytes > step_helpers._MAX_STEP_PACKAGE_BYTES:
+ cli.console.print(
+ f"[red]Error:[/red] Step package exceeds the "
+ f"{step_helpers._MAX_STEP_PACKAGE_BYTES}-byte total size limit"
+ )
+ raise cli.typer.Exit(1)
+
+ # Validate step.yml
+ try:
+ import yaml as _yaml
+
+ step_yml_text = step_yml_content.decode("utf-8")
+ # ``safe_load`` returns None for BOTH an empty document and an
+ # explicit null scalar (``null``, ``~``, ``NULL``), so it cannot
+ # tell them apart on its own. ``compose`` yields no node only for
+ # a genuinely empty document.
+ node = _yaml.compose(step_yml_text)
+ meta = _yaml.safe_load(step_yml_text)
+ is_empty_document = node is None or (
+ meta is None
+ and isinstance(node, _yaml.nodes.ScalarNode)
+ and node.value == ""
+ and node.start_mark.index == node.end_mark.index
+ )
+ except Exception as exc:
+ cli.console.print(f"[red]Error:[/red] Invalid step.yml: {exc}")
+ raise cli.typer.Exit(1)
+
+ # Do NOT coerce with ``or {}`` here: that also turns a FALSY non-mapping
+ # (top-level ``[]``, ``false``, ``0``, ``''``, or an explicit ``null``)
+ # into ``{}`` and silently bypasses this shape check, surfacing the
+ # unrelated "missing 'step.type_key'" error below instead of the real
+ # problem. Only a genuinely empty document defaults to ``{}``.
+ if meta is None and is_empty_document:
+ meta = {}
+ elif not isinstance(meta, dict):
+ cli.console.print("[red]Error:[/red] step.yml must be a YAML mapping")
+ raise cli.typer.Exit(1)
+
+ step_meta = meta.get("step", {})
+ if not isinstance(step_meta, dict):
+ cli.console.print(
+ "[red]Error:[/red] step.yml 'step' field must be a mapping"
+ )
+ raise cli.typer.Exit(1)
+ type_key = step_meta.get("type_key", "")
+ if not type_key:
+ cli.console.print(
+ "[red]Error:[/red] step.yml missing 'step.type_key' field"
+ )
+ raise cli.typer.Exit(1)
+
+ if type_key != step_id:
+ cli.console.print(
+ f"[red]Error:[/red] step.yml type_key ({type_key!r}) does not match "
+ f"catalog ID ({step_id!r})"
+ )
+ raise cli.typer.Exit(1)
+
+ # Write the two required files.
+ try:
+ (tmp_path / "step.yml").write_bytes(step_yml_content)
+ (tmp_path / "__init__.py").write_bytes(init_py_content)
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to write step files to staging directory: {exc}"
+ )
+ raise cli.typer.Exit(1)
+
+ # Optionally download additional package files declared in the catalog entry
+ # (e.g. helper modules). Each entry in ``extra_files`` is a mapping of
+ # relative-path → URL. step.yml and __init__.py are ignored here (already
+ # written). Paths are validated to stay within the step package directory to
+ # prevent path-traversal attacks.
+ for rel_path, file_url in (extra_files or {}).items():
+ if not isinstance(rel_path, str) or not rel_path.strip():
+ cli.console.print(
+ "[red]Error:[/red] Catalog entry 'extra_files' contains an "
+ "empty or non-string path key"
+ )
+ raise cli.typer.Exit(1)
+ if _is_required_package_file(rel_path):
+ continue # already written above
+ # Reject dot-path segments ('', '.', '..') that would refer to the
+ # package directory itself (IsADirectoryError) or escape it.
+ rel_parts = cli.Path(rel_path).parts
+ if not rel_parts or any(seg in ("", ".", "..") for seg in rel_parts):
+ cli.console.print(
+ f"[red]Error:[/red] extra_files path '{rel_path}' is not a "
+ "valid relative file path"
+ )
+ raise cli.typer.Exit(1)
+ if not isinstance(file_url, str) or not file_url.strip():
+ cli.console.print(
+ f"[red]Error:[/red] extra_files entry '{rel_path}' has an "
+ "empty or non-string URL"
+ )
+ raise cli.typer.Exit(1)
+ # Resolve both destination and base to handle any symlinks in tmp_path itself,
+ # ensuring the traversal check is robust even on non-canonical paths.
+ resolved_base = tmp_path.resolve()
+ dest = (tmp_path / rel_path).resolve()
+ try:
+ dest.relative_to(resolved_base)
+ except ValueError:
+ cli.console.print(
+ f"[red]Error:[/red] extra_files path '{rel_path}' is outside "
+ "the step package directory"
+ )
+ raise cli.typer.Exit(1)
+ try:
+ file_content = _safe_fetch(file_url)
+ except Exception as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to download extra file '{rel_path}': {exc}"
+ )
+ raise cli.typer.Exit(1)
+ package_bytes += len(file_content)
+ if package_bytes > step_helpers._MAX_STEP_PACKAGE_BYTES:
+ cli.console.print(
+ f"[red]Error:[/red] Step package exceeds the "
+ f"{step_helpers._MAX_STEP_PACKAGE_BYTES}-byte total size limit"
+ )
+ raise cli.typer.Exit(1)
+ try:
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ dest.write_bytes(file_content)
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to write extra file '{rel_path}': {exc}"
+ )
+ raise cli.typer.Exit(1)
+
+ # Atomically rename the staging directory to the final location.
+ # Both paths are under steps_base_dir (same filesystem), so os.rename()
+ # is atomic on POSIX and won't leave a partially-written directory at
+ # step_dir on failure.
+ try:
+ cli.os.rename(tmp_path, step_dir)
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to install step '{step_id}': {exc}"
+ )
+ raise cli.typer.Exit(1)
+ finally:
+ # Clean up if the rename hasn't moved tmp_path yet (i.e. on any failure).
+ shutil.rmtree(tmp_path, ignore_errors=True)
+
+ step_name = info.get("name") or step_id
+ step_version = info.get("version") or step_meta.get("version") or "0.0.0"
+
+ # Register in step registry
+ registry = StepRegistry(project_root)
+ try:
+ registry.add(
+ step_id,
+ {
+ "name": step_name,
+ "version": step_version,
+ "description": info.get(
+ "description", step_meta.get("description", "")
+ ),
+ "author": info.get("author", step_meta.get("author", "")),
+ "source": "catalog",
+ "catalog_name": info.get("_catalog_name", ""),
+ "type_key": type_key,
+ },
+ )
+ except StepValidationError as exc:
+ # Roll back the just-installed directory so the system isn't left with
+ # an unregistered step package on disk after a registry write failure
+ # (e.g. read-only filesystem, permission denied).
+ shutil.rmtree(step_dir, ignore_errors=True)
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ cli.console.print(f"[green]✓[/green] Step type '{step_name}' ({step_id}) installed")
+ cli.console.print(
+ " Use [cyan]specify workflow step list[/cyan] to verify the installation."
+ )
diff --git a/src/specify_cli/workflows/step/command_info.py b/src/specify_cli/workflows/step/command_info.py
new file mode 100644
index 000000000..c98072d8c
--- /dev/null
+++ b/src/specify_cli/workflows/step/command_info.py
@@ -0,0 +1,78 @@
+"""Command handler for ``specify workflow step info``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import step_app
+
+
+@step_app.command("info")
+def workflow_step_info(
+ step_id: str = cli.typer.Argument(..., help="Step type ID"),
+):
+ """Show details for a step type."""
+ from .. import STEP_REGISTRY
+ from .catalog import StepCatalog, StepCatalogError, StepRegistry
+
+ project_root = cli._require_specify_project()
+ safe_step_id = cli._escape_markup(str(step_id))
+
+ registry = StepRegistry(project_root)
+ installed_meta = registry.get(step_id)
+
+ # Check if it's a built-in
+ builtin_step = STEP_REGISTRY.get(step_id)
+ is_builtin = builtin_step is not None and not installed_meta
+
+ if is_builtin:
+ cli.console.print(
+ f"\n[bold cyan]{safe_step_id}[/bold cyan] [dim](built-in)[/dim]"
+ )
+ cli.console.print(f" Type key: {safe_step_id}")
+ cli.console.print(" [green]Built-in step type[/green]")
+ return
+
+ if installed_meta:
+ name = cli._escape_markup(str(installed_meta.get("name", step_id)))
+ version = cli._escape_markup(str(installed_meta.get("version", "?")))
+ cli.console.print(f"\n[bold cyan]{name}[/bold cyan] ({safe_step_id})")
+ cli.console.print(f" Version: {version}")
+ if installed_meta.get("author"):
+ cli.console.print(
+ f" Author: {cli._escape_markup(str(installed_meta['author']))}"
+ )
+ if installed_meta.get("description"):
+ cli.console.print(
+ f" Description: "
+ f"{cli._escape_markup(str(installed_meta['description']))}"
+ )
+ cli.console.print(" [green]Installed[/green]")
+ return
+
+ # Try catalog
+ catalog = StepCatalog(project_root)
+ try:
+ info = catalog.get_step_info(step_id)
+ except StepCatalogError:
+ info = None
+
+ if info:
+ name = cli._escape_markup(str(info.get("name", step_id)))
+ version = cli._escape_markup(str(info.get("version", "?")))
+ cli.console.print(f"\n[bold cyan]{name}[/bold cyan] ({safe_step_id})")
+ cli.console.print(f" Version: {version}")
+ if info.get("author"):
+ cli.console.print(
+ f" Author: {cli._escape_markup(str(info['author']))}"
+ )
+ if info.get("description"):
+ cli.console.print(
+ f" Description: {cli._escape_markup(str(info['description']))}"
+ )
+ cli.console.print(" [yellow]Not installed[/yellow]")
+ cli.console.print(
+ f"\n Install with: [cyan]specify workflow step add {safe_step_id}[/cyan]"
+ )
+ else:
+ cli.console.print(f"[red]Error:[/red] Step type '{safe_step_id}' not found")
+ raise cli.typer.Exit(1)
diff --git a/src/specify_cli/workflows/step/command_list.py b/src/specify_cli/workflows/step/command_list.py
new file mode 100644
index 000000000..35afdf534
--- /dev/null
+++ b/src/specify_cli/workflows/step/command_list.py
@@ -0,0 +1,49 @@
+"""Command handler for ``specify workflow step list``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import step_app
+
+
+@step_app.command("list")
+def workflow_step_list():
+ """List installed step types (built-in and custom)."""
+ from .. import STEP_REGISTRY
+ from .catalog import StepRegistry
+
+ project_root = cli._require_specify_project()
+ specify_dir = project_root / ".specify"
+
+ # Read installed custom steps from registry only — no dynamic imports
+ installed: dict = {}
+ if specify_dir.exists():
+ registry = StepRegistry(project_root)
+ installed = registry.list()
+
+ cli.console.print("\n[bold cyan]Installed Step Types:[/bold cyan]\n")
+
+ built_in = sorted(k for k in STEP_REGISTRY if k not in installed)
+ if built_in:
+ cli.console.print(" [bold]Built-in:[/bold]")
+ for key in built_in:
+ cli.console.print(f" • {key}")
+ cli.console.print()
+
+ if installed:
+ cli.console.print(" [bold]Custom (installed):[/bold]")
+ for key in sorted(installed):
+ meta = installed[key] or {}
+ name = cli._escape_markup(str(meta.get("name", key)))
+ safe_key = cli._escape_markup(str(key))
+ version = cli._escape_markup(str(meta.get("version", "?")))
+ cli.console.print(f" • [bold]{name}[/bold] ({safe_key}) v{version}")
+ cli.console.print()
+
+ if not built_in and not installed:
+ cli.console.print("[yellow]No step types found.[/yellow]")
+
+ if specify_dir.exists():
+ cli.console.print(
+ " Install a new step type with: [cyan]specify workflow step add <id>[/cyan]"
+ )
diff --git a/src/specify_cli/workflows/step/command_remove.py b/src/specify_cli/workflows/step/command_remove.py
new file mode 100644
index 000000000..58ec7602f
--- /dev/null
+++ b/src/specify_cli/workflows/step/command_remove.py
@@ -0,0 +1,97 @@
+"""Command handler for ``specify workflow step remove``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import step_app
+
+from . import _helpers as step_helpers
+
+
+@step_app.command("remove")
+def workflow_step_remove(
+ step_id: str = cli.typer.Argument(..., help="Step type ID to uninstall"),
+):
+ """Uninstall a custom step type."""
+ from .catalog import StepRegistry, StepValidationError
+
+ project_root = cli._require_specify_project()
+
+ step_helpers._validate_step_id_or_exit(step_id)
+
+ registry = StepRegistry(project_root)
+ in_registry = registry.is_installed(step_id)
+
+ steps_base_dir = step_helpers._resolve_steps_base_dir_or_exit(project_root)
+ step_dir = (steps_base_dir / step_id).resolve()
+ # Defense-in-depth: even though step_helpers._validate_step_id_or_exit rejects path
+ # separators, ensure that the resolved directory is a single child of
+ # steps_base_dir and is not steps_base_dir itself.
+ try:
+ rel_parts = step_dir.relative_to(steps_base_dir).parts
+ except ValueError:
+ cli.console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
+ raise cli.typer.Exit(1)
+ if rel_parts != (step_id,):
+ cli.console.print(f"[red]Error:[/red] Invalid step id '{step_id}'")
+ raise cli.typer.Exit(1)
+
+ dir_exists = step_dir.exists()
+
+ if not in_registry and not dir_exists:
+ cli.console.print(f"[red]Error:[/red] Step type '{step_id}' is not installed")
+ raise cli.typer.Exit(1)
+
+ if not in_registry and dir_exists:
+ # The registry was likely reset due to corruption. Warn the user that the
+ # directory is being removed even though there is no registry entry, so
+ # the orphaned package can be cleaned up and a fresh install attempted.
+ cli.console.print(
+ f"[yellow]Warning:[/yellow] '{step_id}' has no registry entry "
+ "(registry may have been reset). Removing the orphaned directory."
+ )
+
+ if dir_exists and not in_registry:
+ # No registry write needed; just delete the orphaned directory.
+ import shutil
+
+ try:
+ shutil.rmtree(step_dir)
+ except OSError as exc:
+ cli.console.print(
+ f"[red]Error:[/red] Failed to remove step directory {step_dir}: {exc}"
+ )
+ raise cli.typer.Exit(1)
+ elif in_registry:
+ # Remove the registry entry, then the directory. If the directory
+ # delete fails, restore the registry entry so state stays consistent
+ # and a future `step add` isn't blocked by an orphaned directory
+ # with no registry entry.
+ registry_metadata = registry.get(step_id)
+ try:
+ registry.remove(step_id)
+ except StepValidationError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+ if dir_exists:
+ import shutil
+
+ try:
+ shutil.rmtree(step_dir)
+ except OSError as exc:
+ # Restore the original registry entry verbatim (bypass add()
+ # which would overwrite timestamps).
+ try:
+ if registry_metadata is not None:
+ registry.data["steps"][step_id] = registry_metadata
+ registry.save()
+ except Exception as restore_exc: # noqa: BLE001
+ cli.console.print(
+ f"[yellow]Warning:[/yellow] Failed to restore registry entry "
+ f"for '{step_id}' after directory removal failure: {restore_exc}"
+ )
+ cli.console.print(
+ f"[red]Error:[/red] Failed to remove step directory {step_dir}: {exc}"
+ )
+ raise cli.typer.Exit(1)
+ cli.console.print(f"[green]✓[/green] Step type '{step_id}' uninstalled")
diff --git a/src/specify_cli/workflows/step/command_search.py b/src/specify_cli/workflows/step/command_search.py
new file mode 100644
index 000000000..0e905e38d
--- /dev/null
+++ b/src/specify_cli/workflows/step/command_search.py
@@ -0,0 +1,47 @@
+"""Command handler for ``specify workflow step search``."""
+
+from __future__ import annotations
+
+from .. import _commands as cli
+from . import step_app
+
+
+@step_app.command("search")
+def workflow_step_search(
+ query: str | None = cli.typer.Argument(None, help="Search query"),
+):
+ """Search the step type catalog."""
+ from .catalog import StepCatalog, StepCatalogError
+
+ project_root = cli._require_specify_project()
+
+ catalog = StepCatalog(project_root)
+
+ try:
+ results = catalog.search(query=query)
+ except StepCatalogError as exc:
+ cli.console.print(f"[red]Error:[/red] {exc}")
+ raise cli.typer.Exit(1)
+
+ if not results:
+ if query:
+ cli.console.print(
+ f"[yellow]No step types found matching '{query}'.[/yellow]"
+ )
+ else:
+ cli.console.print("[yellow]No step types found in catalog.[/yellow]")
+ return
+
+ cli.console.print(f"\n[bold cyan]Step Types ({len(results)}):[/bold cyan]\n")
+ for step in results:
+ install_note = (
+ "" if step.get("_install_allowed", True) else " [dim](discovery only)[/dim]"
+ )
+ name = cli._escape_markup(str(step.get("name", step.get("id", "?"))))
+ step_id = cli._escape_markup(str(step.get("id", "?")))
+ version = cli._escape_markup(str(step.get("version", "?")))
+ cli.console.print(f" [bold]{name}[/bold] ({step_id}) v{version}{install_note}")
+ desc = step.get("description", "")
+ if desc:
+ cli.console.print(f" {cli._escape_markup(str(desc))}")
+ cli.console.print()
diff --git a/src/specify_cli/workflows/steps/do_while/__init__.py b/src/specify_cli/workflows/step/do_while/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/do_while/__init__.py
rename to src/specify_cli/workflows/step/do_while/__init__.py
diff --git a/src/specify_cli/workflows/steps/fan_in/__init__.py b/src/specify_cli/workflows/step/fan_in/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/fan_in/__init__.py
rename to src/specify_cli/workflows/step/fan_in/__init__.py
diff --git a/src/specify_cli/workflows/steps/fan_out/__init__.py b/src/specify_cli/workflows/step/fan_out/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/fan_out/__init__.py
rename to src/specify_cli/workflows/step/fan_out/__init__.py
diff --git a/src/specify_cli/workflows/steps/gate/__init__.py b/src/specify_cli/workflows/step/gate/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/gate/__init__.py
rename to src/specify_cli/workflows/step/gate/__init__.py
diff --git a/src/specify_cli/workflows/steps/if_then/__init__.py b/src/specify_cli/workflows/step/if_then/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/if_then/__init__.py
rename to src/specify_cli/workflows/step/if_then/__init__.py
diff --git a/src/specify_cli/workflows/steps/init/__init__.py b/src/specify_cli/workflows/step/init/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/init/__init__.py
rename to src/specify_cli/workflows/step/init/__init__.py
diff --git a/src/specify_cli/workflows/steps/prompt/__init__.py b/src/specify_cli/workflows/step/prompt/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/prompt/__init__.py
rename to src/specify_cli/workflows/step/prompt/__init__.py
diff --git a/src/specify_cli/workflows/steps/shell/__init__.py b/src/specify_cli/workflows/step/shell/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/shell/__init__.py
rename to src/specify_cli/workflows/step/shell/__init__.py
diff --git a/src/specify_cli/workflows/steps/slot/__init__.py b/src/specify_cli/workflows/step/slot/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/slot/__init__.py
rename to src/specify_cli/workflows/step/slot/__init__.py
diff --git a/src/specify_cli/workflows/steps/switch/__init__.py b/src/specify_cli/workflows/step/switch/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/switch/__init__.py
rename to src/specify_cli/workflows/step/switch/__init__.py
diff --git a/src/specify_cli/workflows/steps/while_loop/__init__.py b/src/specify_cli/workflows/step/while_loop/__init__.py
similarity index 100%
rename from src/specify_cli/workflows/steps/while_loop/__init__.py
rename to src/specify_cli/workflows/step/while_loop/__init__.py
diff --git a/src/specify_cli/workflows/steps/__init__.py b/src/specify_cli/workflows/steps/__init__.py
deleted file mode 100644
index 0aa9182dd..000000000
--- a/src/specify_cli/workflows/steps/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-"""Auto-discovery for built-in step types."""
diff --git a/tests/specify_cli/workflows/__init__.py b/tests/specify_cli/workflows/__init__.py
new file mode 100644
index 000000000..09457e754
--- /dev/null
+++ b/tests/specify_cli/workflows/__init__.py
@@ -0,0 +1 @@
+"""Tests for workflow CLI commands."""
diff --git a/tests/specify_cli/workflows/catalog/__init__.py b/tests/specify_cli/workflows/catalog/__init__.py
new file mode 100644
index 000000000..c31758b02
--- /dev/null
+++ b/tests/specify_cli/workflows/catalog/__init__.py
@@ -0,0 +1 @@
+"""Tests for workflow catalog CLI commands."""
diff --git a/tests/specify_cli/workflows/catalog/test_command_add.py b/tests/specify_cli/workflows/catalog/test_command_add.py
new file mode 100644
index 000000000..8885d62ec
--- /dev/null
+++ b/tests/specify_cli/workflows/catalog/test_command_add.py
@@ -0,0 +1,30 @@
+"""Tests for ``specify workflow catalog add``."""
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.workflows.catalog import WorkflowCatalog
+
+
+def test_workflow_catalog_add_persists_named_source(project_dir, monkeypatch):
+ monkeypatch.chdir(project_dir)
+
+ result = CliRunner().invoke(
+ app,
+ [
+ "workflow",
+ "catalog",
+ "add",
+ "https://example.com/workflows.json",
+ "--name",
+ "local",
+ ],
+ )
+
+ assert result.exit_code == 0, result.output
+ configs = WorkflowCatalog(project_dir).get_catalog_configs()
+ assert any(
+ config["name"] == "local"
+ and config["url"] == "https://example.com/workflows.json"
+ for config in configs
+ )
diff --git a/tests/specify_cli/workflows/catalog/test_command_list.py b/tests/specify_cli/workflows/catalog/test_command_list.py
new file mode 100644
index 000000000..4f1196f27
--- /dev/null
+++ b/tests/specify_cli/workflows/catalog/test_command_list.py
@@ -0,0 +1,37 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ def test_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch):
+ """User-editable catalog name/url/description must not be parsed as Rich markup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ configs = [
+ {
+ "name": "Bracket [Catalog]",
+ "url": "https://example.com/[cat].json",
+ "description": "desc [with] brackets",
+ "install_allowed": True,
+ },
+ ]
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_catalog_configs",
+ lambda self: [dict(c) for c in configs],
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "catalog", "list"])
+ assert result.exit_code == 0, result.output
+ assert "Bracket [Catalog]" in result.output
+ assert "https://example.com/[cat].json" in result.output
+ assert "desc [with] brackets" in result.output
diff --git a/tests/specify_cli/workflows/catalog/test_command_remove.py b/tests/specify_cli/workflows/catalog/test_command_remove.py
new file mode 100644
index 000000000..22eaa3891
--- /dev/null
+++ b/tests/specify_cli/workflows/catalog/test_command_remove.py
@@ -0,0 +1,19 @@
+"""Tests for ``specify workflow catalog remove``."""
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.workflows.catalog import WorkflowCatalog
+
+
+def test_workflow_catalog_remove_deletes_selected_source(project_dir, monkeypatch):
+ monkeypatch.chdir(project_dir)
+ catalog = WorkflowCatalog(project_dir)
+ catalog.add_catalog("https://example.com/workflows.json", "local")
+
+ result = CliRunner().invoke(app, ["workflow", "catalog", "remove", "0"])
+
+ assert result.exit_code == 0, result.output
+ assert all(
+ config["name"] != "local" for config in catalog.get_catalog_configs()
+ )
diff --git a/tests/specify_cli/workflows/conftest.py b/tests/specify_cli/workflows/conftest.py
new file mode 100644
index 000000000..f956cbb26
--- /dev/null
+++ b/tests/specify_cli/workflows/conftest.py
@@ -0,0 +1,58 @@
+"""Shared fixtures for workflow command tests."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+def temp_dir():
+ """Create a temporary directory for tests."""
+ tmpdir = tempfile.mkdtemp()
+ yield Path(tmpdir)
+ shutil.rmtree(tmpdir, ignore_errors=(sys.platform == "win32"))
+
+
+def project_dir(temp_dir):
+ """Create a mock Spec Kit project with workflow storage."""
+ workflows_dir = temp_dir / ".specify" / "workflows"
+ workflows_dir.mkdir(parents=True, exist_ok=True)
+ return temp_dir
+
+
+def sample_workflow_yaml():
+ """Return a valid minimal workflow YAML string."""
+ return """
+schema_version: "1.0"
+workflow:
+ id: "test-workflow"
+ name: "Test Workflow"
+ version: "1.0.0"
+ description: "A test workflow"
+
+inputs:
+ spec:
+ type: string
+ required: true
+ scope:
+ type: string
+ default: "full"
+
+steps:
+ - id: step-one
+ command: speckit.specify
+ input:
+ args: "{{ inputs.spec }}"
+
+ - id: step-two
+ command: speckit.plan
+ input:
+ args: "{{ steps.step-one.output.command }}"
+"""
diff --git a/tests/specify_cli/workflows/helpers.py b/tests/specify_cli/workflows/helpers.py
new file mode 100644
index 000000000..fafa555e7
--- /dev/null
+++ b/tests/specify_cli/workflows/helpers.py
@@ -0,0 +1,48 @@
+"""Shared helpers for workflow command tests."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+
+class _StubStdin:
+ def __init__(self, tty: bool):
+ self._tty = tty
+
+ def isatty(self):
+ return self._tty
+
+
+class _FakeSys:
+ def __init__(self, tty: bool):
+ self.stdin = _StubStdin(tty)
+
+ def __getattr__(self, name):
+ return getattr(sys, name)
+
+
+def force_gate_stdin(monkeypatch, *, tty: bool):
+ from specify_cli.workflows.step import gate as gate_module
+
+ monkeypatch.setattr(gate_module, "sys", _FakeSys(tty=tty))
+
+
+def write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:
+ workflow_dir = project_root / ".specify" / "workflows" / workflow_id
+ workflow_dir.mkdir(parents=True, exist_ok=True)
+ workflow_path = workflow_dir / "workflow.yml"
+ workflow_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return workflow_path
+
+
+def write_overlay(
+ project_root: Path, workflow_id: str, overlay_id: str, data: dict
+) -> Path:
+ overlay_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
+ overlay_dir.mkdir(parents=True, exist_ok=True)
+ overlay_path = overlay_dir / f"{overlay_id}.yml"
+ overlay_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return overlay_path
diff --git a/tests/specify_cli/workflows/overlay/__init__.py b/tests/specify_cli/workflows/overlay/__init__.py
new file mode 100644
index 000000000..fc8904724
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/__init__.py
@@ -0,0 +1 @@
+"""Tests for workflow overlay CLI commands."""
diff --git a/tests/specify_cli/workflows/overlay/test_command_add.py b/tests/specify_cli/workflows/overlay/test_command_add.py
new file mode 100644
index 000000000..9282f487f
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_add.py
@@ -0,0 +1,513 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+import yaml
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_overlay_add(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
+ )
+ assert result.exit_code == 0, result.output
+ assert "Overlay 'ov1' added" in result.output
+
+ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ assert installed.is_file()
+ data = yaml.safe_load(installed.read_text(encoding="utf-8"))
+ assert data["priority"] == 5
+
+ def test_overlay_add_reuses_yaml_extension(self, project_dir, monkeypatch):
+ """If <id>.yaml already exists, overlay add must write to it instead of creating <id>.yml."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # Pre-create the overlay using the .yaml extension.
+ existing_yaml = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yaml"
+ existing_yaml.parent.mkdir(parents=True, exist_ok=True)
+ existing_yaml.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 1,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 20,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
+ assert result.exit_code == 0, result.output
+
+ # Should have written to the pre-existing .yaml file.
+ assert existing_yaml.is_file()
+ data = yaml.safe_load(existing_yaml.read_text(encoding="utf-8"))
+ assert data["priority"] == 10
+
+ # Must NOT have created a duplicate .yml alongside the .yaml.
+ duplicate_yml = existing_yaml.with_suffix(".yml")
+ assert not duplicate_yml.exists(), "duplicate .yml was created alongside existing .yaml"
+ assert list(existing_yaml.parent.glob(f".{existing_yaml.name}.*.bak")) == []
+
+ def test_overlay_add_with_priority_override_missing_in_file(self, project_dir, monkeypatch):
+ """--priority must fix a missing priority in the overlay file."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # Overlay file has NO priority field
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
+ )
+ assert result.exit_code == 0, result.output
+ assert "Overlay 'ov1' added" in result.output
+
+ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ assert installed.is_file()
+ data = yaml.safe_load(installed.read_text(encoding="utf-8"))
+ assert data["priority"] == 5
+
+ def test_overlay_add_defaults_priority_to_ten(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ assert yaml.safe_load(installed.read_text(encoding="utf-8"))["priority"] == 10
+
+ def test_overlay_add_rejects_non_positive_priority(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(
+ app,
+ ["workflow", "overlay", "add", str(overlay_file), "--priority", "0"],
+ )
+
+ assert result.exit_code == 1
+ assert "must be >= 1" in result.output
+
+ def test_overlay_add_keeps_non_ascii_text_readable(
+ self, project_dir, monkeypatch
+ ):
+ """``overlay add`` must not escape non-ASCII text in the written file.
+
+ Overlay files are documented as hand-authored, so writing them back
+ with ``\\uXXXX`` escapes makes the user's own file unreadable.
+ """
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ message = "Revisar el plan — ¿aprobar? 日本語"
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "replace",
+ "anchor": "a",
+ "step": {
+ "id": "a",
+ "type": "gate",
+ "message": message,
+ "options": ["approve"],
+ },
+ }
+ ],
+ },
+ allow_unicode=True,
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
+ assert result.exit_code == 0, result.output
+
+ installed = (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ )
+ text = installed.read_text(encoding="utf-8")
+ assert message in text, text
+ assert "\\u" not in text and "\\x" not in text, text
+ # The value must still round-trip identically.
+ data = yaml.safe_load(text)
+ assert data["edits"][0]["step"]["message"] == message
+
+
+
+class TestOverlayPathTraversal:
+ """Overlay CLI must stay inside the overlay directory."""
+
+ def test_overlay_add_rejects_traversal_in_workflow_id(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "../wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
+ )
+ assert result.exit_code != 0, result.output
+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
+
+ def test_overlay_add_rejects_traversal_in_overlay_id(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "../../ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
+ )
+ assert result.exit_code != 0, result.output
+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
+
+ def test_overlay_add_rejects_symlinked_target_file(self, project_dir, monkeypatch):
+ """overlay add must not overwrite through a symlinked overlay file target."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+
+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
+ overlay_dir.mkdir(parents=True, exist_ok=True)
+ real_file = overlay_dir / "other.yml"
+ real_file.write_text("sentinel\n", encoding="utf-8")
+ (overlay_dir / "ov1.yml").symlink_to(real_file)
+
+ overlay_file = project_dir / "overlay.yml"
+ overlay_file.write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
+
+ assert result.exit_code != 0, result.output
+ assert "symlinked path" in result.output.lower()
+ assert real_file.read_text(encoding="utf-8") == "sentinel\n"
+
+
+class TestOverlayAddDoesNotClobber:
+ """`overlay add` must not destroy a different overlay sitting at <id>.yml.
+
+ Overlay identity is the manifest `id`, not the filename, so `lint.yml` can
+ legitimately contain `id: format`. The fallback filename-derived target
+ must not overwrite an occupant with a different or unreadable identity.
+ """
+
+ def _setup(self, project_dir: Path, occupant_id: str | None) -> tuple[Path, Path]:
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
+ overlay_dir.mkdir(parents=True, exist_ok=True)
+ if occupant_id is not None:
+ (overlay_dir / "lint.yml").write_text(
+ yaml.safe_dump(
+ {
+ "id": occupant_id,
+ "extends": "wf",
+ "priority": 3,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ incoming = project_dir / "incoming.yml"
+ incoming.write_text(
+ yaml.safe_dump(
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ return overlay_dir, incoming
+
+ def test_add_does_not_clobber_a_different_overlay(
+ self, project_dir, monkeypatch
+ ):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id="format")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ survivor = yaml.safe_load(
+ (overlay_dir / "lint.yml").read_text(encoding="utf-8")
+ )
+ assert survivor["id"] == "format", survivor
+ assert survivor["priority"] == 3, survivor
+ assert [path.name for path in overlay_dir.iterdir() if "bak" in path.name] == []
+
+ def test_add_still_updates_the_same_overlay_in_place(
+ self, project_dir, monkeypatch
+ ):
+ """The guard must only fire for a different overlay id."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id="lint")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 0, result.output
+ updated = yaml.safe_load(
+ (overlay_dir / "lint.yml").read_text(encoding="utf-8")
+ )
+ assert updated["id"] == "lint"
+ assert updated["priority"] == 10
+
+ def test_add_refuses_a_directory_occupant(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = overlay_dir / "lint.yml"
+ occupant.mkdir()
+ (occupant / "precious.txt").write_text("user data", encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ assert "not a regular file" in " ".join(result.output.split())
+ assert occupant.is_dir()
+ assert (occupant / "precious.txt").read_text(encoding="utf-8") == "user data"
+ assert [path.name for path in overlay_dir.iterdir() if "bak" in path.name] == []
+
+ @pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="FIFOs are POSIX-only")
+ def test_add_refuses_a_fifo_occupant(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = overlay_dir / "lint.yml"
+ os.mkfifo(occupant)
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ assert "not a regular file" in " ".join(result.output.split())
+ assert occupant.is_fifo()
+ assert [path.name for path in overlay_dir.iterdir() if "bak" in path.name] == []
+
+ @pytest.mark.parametrize(
+ "raw",
+ [
+ "id: [1, 2\n bad: yaml:\n",
+ "- just\n- a\n- sequence\n",
+ "just a scalar\n",
+ "extends: wf\npriority: 3\n",
+ "id: 5\nextends: wf\npriority: 3\n",
+ ],
+ ids=["malformed", "sequence", "scalar", "missing_id", "non_string_id"],
+ )
+ def test_add_fails_closed_when_the_occupant_cannot_be_identified(
+ self, project_dir, monkeypatch, raw
+ ):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = overlay_dir / "lint.yml"
+ occupant.write_text(raw, encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ assert occupant.read_text(encoding="utf-8") == raw
+ assert [path.name for path in overlay_dir.iterdir() if "bak" in path.name] == []
+
+ def test_add_creates_the_file_when_absent(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ overlay_dir, incoming = self._setup(project_dir, occupant_id=None)
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 0, result.output
+ created = yaml.safe_load(
+ (overlay_dir / "lint.yml").read_text(encoding="utf-8")
+ )
+ assert created["id"] == "lint"
diff --git a/tests/specify_cli/workflows/overlay/test_command_disable.py b/tests/specify_cli/workflows/overlay/test_command_disable.py
new file mode 100644
index 000000000..6ab9c72e0
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_disable.py
@@ -0,0 +1,165 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_overlay as _write_overlay,
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_overlay_disable_and_enable(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "ov1"])
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ ).read_text(encoding="utf-8")
+ )
+ assert data["enabled"] is False
+
+ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "ov1"])
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ ).read_text(encoding="utf-8")
+ )
+ assert data["enabled"] is True
+
+ def test_overlay_list_shows_disabled_overlay(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "enabled": False,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
+ assert result.exit_code == 0, result.output
+ assert "ov1" in result.output
+ assert "disabled" in result.output
+
+
+
+class TestOverlayFilenameVsManifestId:
+ """Overlay identity must come from the manifest ``id`` field, not the filename.
+
+ This matches the project-wide convention: presets use ``preset.id``,
+ extensions use ``extension.id``, workflows use ``workflow.id``, and
+ workflow steps use ``step.type_key``. Overlays must follow the same pattern.
+ """
+
+ def _write_mismatched_overlay(
+ self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict
+ ) -> Path:
+ """Write an overlay file where filename != manifest id."""
+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
+ ov_dir.mkdir(parents=True, exist_ok=True)
+ ov_path = ov_dir / filename
+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return ov_path
+
+ def test_enable_disable_with_mismatched_filename(self, project_dir, monkeypatch):
+ """enable/disable must work when filename != manifest id."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "custom.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "lint"])
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
+ encoding="utf-8"
+ )
+ )
+ assert data["enabled"] is False
+
+ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "lint"])
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
+ encoding="utf-8"
+ )
+ )
+ assert data["enabled"] is True
diff --git a/tests/specify_cli/workflows/overlay/test_command_enable.py b/tests/specify_cli/workflows/overlay/test_command_enable.py
new file mode 100644
index 000000000..e764b23de
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_enable.py
@@ -0,0 +1,32 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayPathTraversal:
+ """Overlay CLI must stay inside the overlay directory."""
+
+ def test_overlay_enable_rejects_traversal(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "../other"])
+ assert result.exit_code != 0, result.output
+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
diff --git a/tests/specify_cli/workflows/overlay/test_command_list.py b/tests/specify_cli/workflows/overlay/test_command_list.py
new file mode 100644
index 000000000..dc1a43ece
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_list.py
@@ -0,0 +1,239 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import typer
+import yaml
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_overlay as _write_overlay,
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_overlay_list(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
+ assert result.exit_code == 0, result.output
+ assert "ov1" in result.output
+
+
+
+class TestOverlayFilenameVsManifestId:
+ """Overlay identity must come from the manifest ``id`` field, not the filename.
+
+ This matches the project-wide convention: presets use ``preset.id``,
+ extensions use ``extension.id``, workflows use ``workflow.id``, and
+ workflow steps use ``step.type_key``. Overlays must follow the same pattern.
+ """
+
+ def _write_mismatched_overlay(
+ self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict
+ ) -> Path:
+ """Write an overlay file where filename != manifest id."""
+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
+ ov_dir.mkdir(parents=True, exist_ok=True)
+ ov_path = ov_dir / filename
+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return ov_path
+
+ def test_find_overlay_by_manifest_id_not_filename(self, project_dir, monkeypatch):
+ """_find_overlay_file must locate overlays by manifest id, not filename."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # File is named "custom.yml" but manifest declares id: "lint"
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "custom.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ },
+ )
+
+ from specify_cli.workflows.overlay.operations import _find_overlay_file
+
+ # Must find by manifest id "lint", not by filename "custom"
+ found = _find_overlay_file(project_dir, "wf", "lint")
+ assert found is not None
+ assert found.name == "custom.yml"
+
+ # Must NOT find by filename stem "custom"
+ not_found = _find_overlay_file(project_dir, "wf", "custom")
+ assert not_found is None
+
+ def test_duplicate_manifest_id_is_rejected(self, project_dir, monkeypatch):
+ """Two files with the same manifest ID are ambiguous."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # Two files, both declare id: "lint"
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "aaa.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ },
+ )
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "zzz.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 20,
+ "edits": [{"remove": "a"}],
+ },
+ )
+
+ from specify_cli.workflows.overlay.operations import _find_overlay_file
+
+ with pytest.raises(typer.Exit):
+ _find_overlay_file(project_dir, "wf", "lint")
+
+
+
+class TestOverlayPathTraversal:
+ """Overlay CLI must stay inside the overlay directory."""
+
+ @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])
+ def test_overlay_operations_reject_reserved_workflow_id(
+ self, project_dir, monkeypatch, workflow_id
+ ):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ result = runner.invoke(app, ["workflow", "overlay", "list", workflow_id])
+ assert result.exit_code != 0, result.output
+ assert "Invalid" in result.output or "reserved" in result.output.lower()
+
+ def test_overlay_rejects_symlinked_overlays_dir(self, project_dir, monkeypatch, tmp_path):
+ """Overlay commands must reject a symlinked .specify/workflows/overlays directory."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+
+ # Create a symlinked overlays directory pointing outside the project
+ outside_dir = tmp_path / "outside"
+ outside_dir.mkdir()
+ overlays_dir = project_dir / ".specify" / "workflows" / "overlays"
+ overlays_dir.symlink_to(outside_dir)
+
+ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
+ assert result.exit_code != 0, result.output
+ assert "symlink" in result.output.lower()
+
+ def test_overlay_list_rejects_symlinked_per_workflow_dir(self, project_dir, monkeypatch, tmp_path):
+ """Overlay list must reject a symlinked per-workflow overlay directory."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+
+ # Create a real overlay directory outside the project.
+ outside_dir = tmp_path / "outside_wf"
+ outside_dir.mkdir()
+ outside_dir.joinpath("evil.yml").write_text(
+ yaml.safe_dump(
+ {
+ "id": "evil",
+ "extends": "wf",
+ "priority": 100,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "evil-step", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ # Symlink the per-workflow overlay directory to the outside location.
+ overlays_root = project_dir / ".specify" / "workflows" / "overlays"
+ overlays_root.mkdir(parents=True, exist_ok=True)
+ symlink_dir = overlays_root / "wf"
+ symlink_dir.symlink_to(outside_dir)
+
+ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
+ assert result.exit_code != 0, result.output
+ assert "symlink" in result.output.lower()
+
+ def test_overlay_list_reports_invalid_yaml_cleanly(self, project_dir, monkeypatch):
+ """Overlay list should surface malformed overlay YAML as a clean user error."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
+ overlay_dir.mkdir(parents=True, exist_ok=True)
+ (overlay_dir / "broken.yml").write_text("id: broken\nextends: wf\npriority: [\n", encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
+
+ assert result.exit_code != 0, result.output
+ assert "Invalid YAML" in result.output
diff --git a/tests/specify_cli/workflows/overlay/test_command_remove.py b/tests/specify_cli/workflows/overlay/test_command_remove.py
new file mode 100644
index 000000000..561f81447
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_remove.py
@@ -0,0 +1,172 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_overlay as _write_overlay,
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_overlay_remove(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "ov1"])
+ assert result.exit_code == 0, result.output
+ assert not (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ ).exists()
+
+
+
+class TestOverlayFilenameVsManifestId:
+ """Overlay identity must come from the manifest ``id`` field, not the filename.
+
+ This matches the project-wide convention: presets use ``preset.id``,
+ extensions use ``extension.id``, workflows use ``workflow.id``, and
+ workflow steps use ``step.type_key``. Overlays must follow the same pattern.
+ """
+
+ def _write_mismatched_overlay(
+ self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict
+ ) -> Path:
+ """Write an overlay file where filename != manifest id."""
+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
+ ov_dir.mkdir(parents=True, exist_ok=True)
+ ov_path = ov_dir / filename
+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return ov_path
+
+ def test_remove_with_mismatched_filename(self, project_dir, monkeypatch):
+ """remove must work when filename != manifest id."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "custom.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "lint"])
+ assert result.exit_code == 0, result.output
+ assert not (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml"
+ ).exists()
+
+
+
+class TestOverlayPathTraversal:
+ """Overlay CLI must stay inside the overlay directory."""
+
+ def test_overlay_remove_cannot_escape_overlays_dir(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # Create a base workflow file that would be the traversal target.
+ target = project_dir / ".specify" / "workflows" / "wf" / "workflow.yml"
+ assert target.is_file()
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "remove", "wf", "../wf/workflow"]
+ )
+ assert result.exit_code != 0, result.output
+ assert target.is_file()
+ assert "Invalid" in result.output or "traversal" in result.output.lower()
+
+ def test_overlay_remove_rejects_symlink(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
+ real_file = overlay_dir / "ov1.yml"
+ symlink_file = overlay_dir / "symlink.yml"
+ symlink_file.symlink_to(real_file)
+
+ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "symlink"])
+ assert result.exit_code != 0, result.output
+ assert real_file.is_file()
+ assert "symlink" in result.output.lower() or "Invalid" in result.output
diff --git a/tests/specify_cli/workflows/overlay/test_command_set_priority.py b/tests/specify_cli/workflows/overlay/test_command_set_priority.py
new file mode 100644
index 000000000..f4290e29a
--- /dev/null
+++ b/tests/specify_cli/workflows/overlay/test_command_set_priority.py
@@ -0,0 +1,244 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_overlay as _write_overlay,
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_overlay_set_priority_keeps_non_ascii_text_readable(
+ self, project_dir, monkeypatch
+ ):
+ """Toggling an overlay must not mangle non-ASCII text already in it."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ message = "Revisar el plan — ¿aprobar? 日本語"
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "replace",
+ "anchor": "a",
+ "step": {
+ "id": "a",
+ "type": "gate",
+ "message": message,
+ "options": ["approve"],
+ },
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf", "ov1", "20"]
+ )
+ assert result.exit_code == 0, result.output
+
+ text = (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ ).read_text(encoding="utf-8")
+ assert message in text, text
+ assert "\\u" not in text and "\\x" not in text, text
+ data = yaml.safe_load(text)
+ assert data["priority"] == 20
+ assert data["edits"][0]["step"]["message"] == message
+
+ def test_overlay_set_priority(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf", "ov1", "20"]
+ )
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (
+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
+ ).read_text(encoding="utf-8")
+ )
+ assert data["priority"] == 20
+ assert list(
+ (project_dir / ".specify" / "workflows" / "overlays" / "wf").glob(
+ ".ov1.yml.*.bak"
+ )
+ ) == []
+
+ def test_overlay_set_priority_rejects_zero(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf", "ov1", "0"]
+ )
+
+ assert result.exit_code == 1
+ assert "must be >= 1" in result.output
+
+ def test_overlay_set_priority_rejects_ids_with_trailing_newline(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf", "ov1\n", "20"]
+ )
+ assert result.exit_code == 1
+ assert "Invalid overlay ID" in result.output
+
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf\n", "ov1", "20"]
+ )
+ assert result.exit_code == 1
+ assert "Invalid workflow ID" in result.output
+
+
+
+class TestOverlayFilenameVsManifestId:
+ """Overlay identity must come from the manifest ``id`` field, not the filename.
+
+ This matches the project-wide convention: presets use ``preset.id``,
+ extensions use ``extension.id``, workflows use ``workflow.id``, and
+ workflow steps use ``step.type_key``. Overlays must follow the same pattern.
+ """
+
+ def _write_mismatched_overlay(
+ self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict
+ ) -> Path:
+ """Write an overlay file where filename != manifest id."""
+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
+ ov_dir.mkdir(parents=True, exist_ok=True)
+ ov_path = ov_dir / filename
+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
+ return ov_path
+
+ def test_set_priority_with_mismatched_filename(self, project_dir, monkeypatch):
+ """set-priority must work when filename != manifest id."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ self._write_mismatched_overlay(
+ project_dir,
+ "wf",
+ "custom.yml",
+ "lint",
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "overlay", "set-priority", "wf", "lint", "25"])
+ assert result.exit_code == 0, result.output
+ data = yaml.safe_load(
+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
+ encoding="utf-8"
+ )
+ )
+ assert data["priority"] == 25
+
+
+
+class TestOverlayPathTraversal:
+ """Overlay CLI must stay inside the overlay directory."""
+
+ def test_overlay_set_priority_rejects_traversal(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ result = runner.invoke(
+ app, ["workflow", "overlay", "set-priority", "wf", "../other", "10"]
+ )
+ assert result.exit_code != 0, result.output
+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
diff --git a/tests/specify_cli/workflows/step/__init__.py b/tests/specify_cli/workflows/step/__init__.py
new file mode 100644
index 000000000..ad388a975
--- /dev/null
+++ b/tests/specify_cli/workflows/step/__init__.py
@@ -0,0 +1 @@
+"""Tests for workflow step CLI commands."""
diff --git a/tests/specify_cli/workflows/step/catalog/__init__.py b/tests/specify_cli/workflows/step/catalog/__init__.py
new file mode 100644
index 000000000..14ba41a84
--- /dev/null
+++ b/tests/specify_cli/workflows/step/catalog/__init__.py
@@ -0,0 +1 @@
+"""Tests for workflow step catalog CLI commands."""
diff --git a/tests/specify_cli/workflows/step/catalog/test_command_add.py b/tests/specify_cli/workflows/step/catalog/test_command_add.py
new file mode 100644
index 000000000..168dde0ab
--- /dev/null
+++ b/tests/specify_cli/workflows/step/catalog/test_command_add.py
@@ -0,0 +1,31 @@
+"""Tests for ``specify workflow step catalog add``."""
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.workflows.step.catalog import StepCatalog
+
+
+def test_workflow_step_catalog_add_persists_named_source(project_dir, monkeypatch):
+ monkeypatch.chdir(project_dir)
+
+ result = CliRunner().invoke(
+ app,
+ [
+ "workflow",
+ "step",
+ "catalog",
+ "add",
+ "https://example.com/steps.json",
+ "--name",
+ "local",
+ ],
+ )
+
+ assert result.exit_code == 0, result.output
+ configs = StepCatalog(project_dir).get_catalog_configs()
+ assert any(
+ config["name"] == "local"
+ and config["url"] == "https://example.com/steps.json"
+ for config in configs
+ )
diff --git a/tests/specify_cli/workflows/step/catalog/test_command_list.py b/tests/specify_cli/workflows/step/catalog/test_command_list.py
new file mode 100644
index 000000000..6aff5d356
--- /dev/null
+++ b/tests/specify_cli/workflows/step/catalog/test_command_list.py
@@ -0,0 +1,37 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ def test_step_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch):
+ """User-editable step-catalog name/url/description must not be parsed as Rich markup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ configs = [
+ {
+ "name": "Bracket [Step]",
+ "url": "https://example.com/[step].json",
+ "description": "step [with] brackets",
+ "install_allowed": True,
+ },
+ ]
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_catalog_configs",
+ lambda self: [dict(c) for c in configs],
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "catalog", "list"])
+ assert result.exit_code == 0, result.output
+ assert "Bracket [Step]" in result.output
+ assert "https://example.com/[step].json" in result.output
+ assert "step [with] brackets" in result.output
diff --git a/tests/specify_cli/workflows/step/catalog/test_command_remove.py b/tests/specify_cli/workflows/step/catalog/test_command_remove.py
new file mode 100644
index 000000000..71ebf937c
--- /dev/null
+++ b/tests/specify_cli/workflows/step/catalog/test_command_remove.py
@@ -0,0 +1,23 @@
+"""Tests for ``specify workflow step catalog remove``."""
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+from specify_cli.workflows.step.catalog import StepCatalog
+
+
+def test_workflow_step_catalog_remove_deletes_selected_source(
+ project_dir, monkeypatch
+):
+ monkeypatch.chdir(project_dir)
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/steps.json", "local")
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "catalog", "remove", "0"]
+ )
+
+ assert result.exit_code == 0, result.output
+ assert all(
+ config["name"] != "local" for config in catalog.get_catalog_configs()
+ )
diff --git a/tests/specify_cli/workflows/step/test_command_add.py b/tests/specify_cli/workflows/step/test_command_add.py
new file mode 100644
index 000000000..e19c53c6b
--- /dev/null
+++ b/tests/specify_cli/workflows/step/test_command_add.py
@@ -0,0 +1,606 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+
+class TestWorkflowStepAddCLI:
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_add_rejects_symlinked_steps_base_dir(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ outside = project_dir.parent / "outside-steps"
+ outside.mkdir(parents=True, exist_ok=True)
+ steps_link = project_dir / ".specify" / "workflows" / "steps"
+ steps_link.symlink_to(outside, target_is_directory=True)
+
+ def _fake_get_step_info(self, step_id):
+ return {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ }
+
+ monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
+
+ assert result.exit_code != 0
+ assert "Refusing to use symlinked step directory" in result.output
+
+ def test_add_rejects_oversized_step_response(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+ from specify_cli.workflows.step.catalog import StepCatalog
+ from specify_cli.authentication import http as auth_http
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ },
+ )
+
+ class _FakeResponse:
+ def __init__(self, url):
+ self.url = url
+ self.body = b"x" * 500
+ self.offset = 0
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def getheader(self, name):
+ return None
+
+ def geturl(self):
+ return self.url
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self.body) - self.offset
+ chunk = self.body[self.offset : self.offset + size]
+ self.offset += len(chunk)
+ return chunk
+
+ monkeypatch.setattr(
+ auth_http,
+ "open_url",
+ lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code != 0
+ assert (
+ "responseexceedsthe100-byteworkflowsizelimit"
+ in "".join(result.output.split())
+ )
+ assert not (
+ project_dir / ".specify" / "workflows" / "steps" / "my-step"
+ ).exists()
+
+ @pytest.mark.parametrize(
+ "step_yml_body", [b"[]", b"false", b"0", b"''", b"null", b"~", b"NULL"]
+ )
+ def test_add_rejects_falsy_non_mapping_step_yml(
+ self, project_dir, monkeypatch, step_yml_body
+ ):
+ """A FALSY non-mapping step.yml document ([], false, 0, '') must be
+ reported as "step.yml must be a YAML mapping", not silently coerced by
+ ``or {}`` into {} and then misreported as the unrelated "missing
+ 'step.type_key'" error — matching how a TRUTHY non-mapping document
+ (e.g. a bare string) already reports the mapping-shape error. An
+ explicit null scalar (null/~/NULL) parses to the same ``None`` as a
+ genuinely empty document, so it must be distinguished (via
+ ``yaml.compose``) and rejected too, rather than defaulting to {}."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+ from specify_cli.authentication import http as auth_http
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ },
+ )
+
+ class _FakeResponse:
+ def __init__(self, url):
+ self.url = url
+ self.body = step_yml_body if url.endswith("step.yml") else b""
+ self.offset = 0
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def getheader(self, name):
+ return None
+
+ def geturl(self):
+ return self.url
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self.body) - self.offset
+ chunk = self.body[self.offset : self.offset + size]
+ self.offset += len(chunk)
+ return chunk
+
+ monkeypatch.setattr(
+ auth_http,
+ "open_url",
+ lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code != 0
+ assert "step.yml must be a YAML mapping" in result.output
+ assert not (
+ project_dir / ".specify" / "workflows" / "steps" / "my-step"
+ ).exists()
+
+ @pytest.mark.parametrize(
+ ("catalog_fields", "expected"),
+ [
+ ({"url": 123}, "malformed step.yml URL"),
+ (
+ {
+ "step_yml_url": [],
+ "url": "https://example.com/step.yml",
+ },
+ "malformed step.yml URL",
+ ),
+ (
+ {
+ "url": "https://example.com/step.yml",
+ "init_url": 123,
+ },
+ "malformed __init__.py URL",
+ ),
+ ],
+ )
+ def test_add_rejects_non_string_required_urls_before_network(
+ self, project_dir, monkeypatch, catalog_fields, expected
+ ):
+ from typer.testing import CliRunner
+
+ from specify_cli import app
+ from specify_cli.authentication import http as auth_http
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "_install_allowed": True,
+ **catalog_fields,
+ },
+ )
+ monkeypatch.setattr(
+ auth_http,
+ "open_url",
+ lambda *args, **kwargs: (_ for _ in ()).throw(
+ AssertionError("download should not start")
+ ),
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert expected in result.output
+ assert not (
+ project_dir / ".specify" / "workflows" / "steps" / "my-step"
+ ).exists()
+
+ @pytest.mark.parametrize(
+ ("alias", "protected_name"),
+ [
+ ("./step.yml", "step.yml"),
+ ("step.yml/", "step.yml"),
+ ("STEP.YML", "step.yml"),
+ (".\\step.yml", "step.yml"),
+ ("./__init__.py", "__init__.py"),
+ ("__init__.py/", "__init__.py"),
+ ("__INIT__.PY", "__init__.py"),
+ (".\\__init__.py", "__init__.py"),
+ ],
+ )
+ def test_add_does_not_overwrite_required_files_through_path_aliases(
+ self, project_dir, monkeypatch, alias, protected_name
+ ):
+ from typer.testing import CliRunner
+
+ from specify_cli import app
+ from specify_cli.authentication import http as auth_http
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ alias_url = "https://example.com/overwrite"
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {alias: alias_url},
+ },
+ )
+ bodies = {
+ "https://example.com/step.yml": b"step:\n type_key: my-step\n",
+ "https://example.com/__init__.py": b"# trusted init\n",
+ }
+ requested_urls: list[str] = []
+
+ class _FakeResponse:
+ def __init__(self, url):
+ self.url = url
+ self.body = bodies[url]
+ self.offset = 0
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def geturl(self):
+ return self.url
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self.body) - self.offset
+ chunk = self.body[self.offset : self.offset + size]
+ self.offset += len(chunk)
+ return chunk
+
+ def fake_open_url(url, timeout=30, redirect_validator=None):
+ requested_urls.append(url)
+ return _FakeResponse(url)
+
+ monkeypatch.setattr(auth_http, "open_url", fake_open_url)
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code == 0, result.output
+ assert alias_url not in requested_urls
+ installed_dir = (
+ project_dir / ".specify" / "workflows" / "steps" / "my-step"
+ )
+ assert (installed_dir / protected_name).read_bytes() == bodies[
+ f"https://example.com/{protected_name}"
+ ]
+
+ def test_add_rejects_too_many_package_files_before_network(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+
+ from specify_cli import app
+ from specify_cli.authentication import http as auth_http
+ from specify_cli.workflows.step import _helpers as step_helpers
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(step_helpers, "_MAX_STEP_PACKAGE_FILES", 3)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {
+ "one.py": "https://example.com/one.py",
+ "two.py": "https://example.com/two.py",
+ },
+ },
+ )
+ monkeypatch.setattr(
+ auth_http,
+ "open_url",
+ lambda *args, **kwargs: (_ for _ in ()).throw(
+ AssertionError("download should not start")
+ ),
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "exceeding the 3-file limit" in result.output
+ steps_dir = project_dir / ".specify" / "workflows" / "steps"
+ assert not (steps_dir / "my-step").exists()
+ assert list(steps_dir.glob("speckit_step_tmp_*")) == []
+
+ def test_add_rejects_package_over_cumulative_size_and_cleans_staging(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+
+ from specify_cli import app
+ from specify_cli.authentication import http as auth_http
+ from specify_cli.workflows.step import _helpers as step_helpers
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(step_helpers, "_MAX_STEP_PACKAGE_BYTES", 40)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda self, step_id: {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {
+ "helper.py": "https://example.com/helper.py",
+ },
+ },
+ )
+
+ bodies = {
+ "https://example.com/step.yml": b"step:\n type_key: my-step\n",
+ "https://example.com/__init__.py": b"# init\n",
+ "https://example.com/helper.py": b"0123456789",
+ }
+
+ class _FakeResponse:
+ def __init__(self, url):
+ self.url = url
+ self.body = bodies[url]
+ self.offset = 0
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def getheader(self, name):
+ return None
+
+ def geturl(self):
+ return self.url
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self.body) - self.offset
+ chunk = self.body[self.offset : self.offset + size]
+ self.offset += len(chunk)
+ return chunk
+
+ monkeypatch.setattr(
+ auth_http,
+ "open_url",
+ lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "add", "my-step"]
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "40-byte total size limit" in result.output
+ steps_dir = project_dir / ".specify" / "workflows" / "steps"
+ assert not (steps_dir / "my-step").exists()
+ assert list(steps_dir.glob("speckit_step_tmp_*")) == []
+
+ def test_add_rejects_non_string_extra_files_key(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+ from specify_cli.authentication import http as auth_http
+
+ monkeypatch.chdir(project_dir)
+
+ def _fake_get_step_info(self, step_id):
+ return {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {
+ 123: "https://example.com/helper.py",
+ },
+ }
+
+ class _FakeResponse:
+ def __init__(self, url: str):
+ self.url = url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def read(self, size=-1):
+ if getattr(self, "_read", False):
+ return b""
+ self._read = True
+ if self.url.endswith("/step.yml"):
+ return b"step:\n type_key: my-step\n"
+ return b""
+
+ def geturl(self):
+ return self.url
+
+ def _fake_open_url(url, timeout=30, redirect_validator=None):
+ return _FakeResponse(url)
+
+ monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
+ monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
+
+ assert result.exit_code != 0
+ assert "non-string path key" in result.output
+
+ @pytest.mark.parametrize(
+ "rel_path,expected",
+ [
+ ("", "empty or non-string path key"),
+ (".", "not a valid relative file path"),
+ ("..", "not a valid relative file path"),
+ ("sub/../x", "not a valid relative file path"),
+ ],
+ )
+ def test_add_rejects_invalid_extra_files_path(
+ self, project_dir, monkeypatch, rel_path, expected
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+ from specify_cli.authentication import http as auth_http
+
+ monkeypatch.chdir(project_dir)
+
+ def _fake_get_step_info(self, step_id):
+ return {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {rel_path: "https://example.com/helper.py"},
+ }
+
+ class _FakeResponse:
+ def __init__(self, url: str):
+ self.url = url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def read(self, size=-1):
+ if getattr(self, "_read", False):
+ return b""
+ self._read = True
+ if self.url.endswith("/step.yml"):
+ return b"step:\n type_key: my-step\n"
+ return b""
+
+ def geturl(self):
+ return self.url
+
+ def _fake_open_url(url, timeout=30, redirect_validator=None):
+ return _FakeResponse(url)
+
+ monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
+ monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
+
+ assert result.exit_code != 0
+ assert expected in result.output
+
+ def test_add_rejects_non_string_extra_files_url(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+ from specify_cli.authentication import http as auth_http
+
+ monkeypatch.chdir(project_dir)
+
+ def _fake_get_step_info(self, step_id):
+ return {
+ "id": step_id,
+ "name": "Test Step",
+ "url": "https://example.com/step.yml",
+ "init_url": "https://example.com/__init__.py",
+ "_install_allowed": True,
+ "extra_files": {"helper.py": None},
+ }
+
+ class _FakeResponse:
+ def __init__(self, url: str):
+ self.url = url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return False
+
+ def read(self, size=-1):
+ if getattr(self, "_read", False):
+ return b""
+ self._read = True
+ if self.url.endswith("/step.yml"):
+ return b"step:\n type_key: my-step\n"
+ return b""
+
+ def geturl(self):
+ return self.url
+
+ def _fake_open_url(url, timeout=30, redirect_validator=None):
+ return _FakeResponse(url)
+
+ monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
+ monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
+
+ assert result.exit_code != 0
+ assert "empty or non-string URL" in result.output
diff --git a/tests/specify_cli/workflows/step/test_command_info.py b/tests/specify_cli/workflows/step/test_command_info.py
new file mode 100644
index 000000000..663b12be4
--- /dev/null
+++ b/tests/specify_cli/workflows/step/test_command_info.py
@@ -0,0 +1,63 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowStepRichMarkup:
+ """Step discovery commands render metadata as literal text."""
+
+ METADATA = {
+ "id": "[magenta]step-id[/magenta]",
+ "name": "[red]Step Name[/red]",
+ "version": "[green]1.0.0[/green]",
+ "author": "[yellow]Author[/yellow]",
+ "description": "[blue]Description[/blue]",
+ }
+
+ def test_info_escapes_catalog_metadata(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog, StepRegistry
+
+ metadata = dict(self.METADATA)
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(StepRegistry, "get", lambda _registry, step_id: None)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda _catalog, step_id: metadata,
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "info", metadata["id"]]
+ )
+
+ assert result.exit_code == 0, result.output
+ for value in metadata.values():
+ assert value in result.output
+
+ def test_info_escapes_missing_step_id(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog, StepRegistry
+
+ step_id = "[red]missing[/red]"
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(StepRegistry, "get", lambda _registry, step_id: None)
+ monkeypatch.setattr(
+ StepCatalog,
+ "get_step_info",
+ lambda _catalog, step_id: None,
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "step", "info", step_id]
+ )
+
+ assert result.exit_code == 1, result.output
+ assert step_id in result.output
diff --git a/tests/specify_cli/workflows/step/test_command_list.py b/tests/specify_cli/workflows/step/test_command_list.py
new file mode 100644
index 000000000..e225eea93
--- /dev/null
+++ b/tests/specify_cli/workflows/step/test_command_list.py
@@ -0,0 +1,40 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowStepRichMarkup:
+ """Step discovery commands render metadata as literal text."""
+
+ METADATA = {
+ "id": "[magenta]step-id[/magenta]",
+ "name": "[red]Step Name[/red]",
+ "version": "[green]1.0.0[/green]",
+ "author": "[yellow]Author[/yellow]",
+ "description": "[blue]Description[/blue]",
+ }
+
+ def test_list_escapes_installed_metadata(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepRegistry
+
+ metadata = dict(self.METADATA)
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ StepRegistry,
+ "list",
+ lambda _registry: {metadata["id"]: metadata},
+ )
+
+ result = CliRunner().invoke(app, ["workflow", "step", "list"])
+
+ assert result.exit_code == 0, result.output
+ assert metadata["name"] in result.output
+ assert metadata["id"] in result.output
+ assert metadata["version"] in result.output
diff --git a/tests/specify_cli/workflows/step/test_command_remove.py b/tests/specify_cli/workflows/step/test_command_remove.py
new file mode 100644
index 000000000..a6bd5781c
--- /dev/null
+++ b/tests/specify_cli/workflows/step/test_command_remove.py
@@ -0,0 +1,94 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+
+class TestWorkflowStepRemoveCLI:
+ """Test the 'specify workflow step remove' CLI command edge cases."""
+
+ def test_remove_orphaned_directory(self, project_dir, monkeypatch):
+ """step remove works when directory exists but registry entry is missing.
+
+ This covers the case where the registry was reset due to corruption.
+ """
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+
+ # Create an orphaned step directory (no registry entry)
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "orphan-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: orphan-step\n", encoding="utf-8"
+ )
+ (step_dir / "__init__.py").write_text("", encoding="utf-8")
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "remove", "orphan-step"])
+
+ assert result.exit_code == 0, result.output
+ assert not step_dir.exists()
+ # Warning should be printed about missing registry entry
+ assert "Warning" in result.output or "warning" in result.output.lower()
+
+ def test_remove_not_installed(self, project_dir, monkeypatch):
+ """step remove fails cleanly when neither directory nor registry entry exist."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "remove", "ghost-step"])
+
+ assert result.exit_code != 0
+ assert "not installed" in result.output
+
+ def test_remove_registered_step(self, project_dir, monkeypatch):
+ """step remove works normally when both directory and registry entry exist."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepRegistry
+
+ monkeypatch.chdir(project_dir)
+
+ # Set up a registered step with a directory
+ registry = StepRegistry(project_dir)
+ registry.add("my-step", {"name": "My Step", "type_key": "my-step", "version": "1.0.0"})
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "my-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: my-step\n", encoding="utf-8"
+ )
+ (step_dir / "__init__.py").write_text("", encoding="utf-8")
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "remove", "my-step"])
+
+ assert result.exit_code == 0, result.output
+ assert not step_dir.exists()
+ registry2 = StepRegistry(project_dir)
+ assert not registry2.is_installed("my-step")
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_remove_rejects_symlinked_steps_base_dir(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ outside = project_dir.parent / "outside-steps"
+ outside.mkdir(parents=True, exist_ok=True)
+ steps_link = project_dir / ".specify" / "workflows" / "steps"
+ steps_link.symlink_to(outside, target_is_directory=True)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "step", "remove", "my-step"])
+
+ assert result.exit_code != 0
+ assert "Refusing to use symlinked step directory" in result.output
diff --git a/tests/specify_cli/workflows/step/test_command_search.py b/tests/specify_cli/workflows/step/test_command_search.py
new file mode 100644
index 000000000..bd9982da0
--- /dev/null
+++ b/tests/specify_cli/workflows/step/test_command_search.py
@@ -0,0 +1,39 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowStepRichMarkup:
+ """Step discovery commands render metadata as literal text."""
+
+ METADATA = {
+ "id": "[magenta]step-id[/magenta]",
+ "name": "[red]Step Name[/red]",
+ "version": "[green]1.0.0[/green]",
+ "author": "[yellow]Author[/yellow]",
+ "description": "[blue]Description[/blue]",
+ }
+
+ def test_search_escapes_catalog_metadata(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.step.catalog import StepCatalog
+
+ metadata = dict(self.METADATA)
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ StepCatalog, "search", lambda _catalog, query=None: [metadata]
+ )
+
+ result = CliRunner().invoke(app, ["workflow", "step", "search"])
+
+ assert result.exit_code == 0, result.output
+ assert metadata["name"] in result.output
+ assert metadata["id"] in result.output
+ assert metadata["version"] in result.output
+ assert metadata["description"] in result.output
diff --git a/tests/specify_cli/workflows/test_command_add.py b/tests/specify_cli/workflows/test_command_add.py
new file mode 100644
index 000000000..263fe79ad
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_add.py
@@ -0,0 +1,3206 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+
+import pytest
+import typer
+import yaml
+
+from typer.testing import CliRunner
+
+from specify_cli import app
+
+runner = CliRunner()
+
+
+
+class TestWorkflowAddCaseInsensitiveSuffix:
+ """`workflow add` must detect a local YAML file case-insensitively, matching
+ `workflow run` (_commands.py:workflow_run) and the engine loader
+ (engine.py:WorkflowEngine.load_workflow), which both use `.suffix.lower()`.
+ Without it, `workflow run Sample.YAML` works but `workflow add Sample.YAML`
+ fails — an add/run inconsistency for an uppercase extension."""
+
+ def test_plain_path_accepts_uppercase_extension(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ src = temp_dir / "Sample.YAML"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ # Before the fix: `.suffix in (...)` is case-sensitive, so ".YAML" is not
+ # recognized as a local file; the path falls through to catalog lookup
+ # and fails. After the fix it installs like the lowercase happy path.
+ assert result.exit_code == 0, result.output
+ assert "installed" in result.output
+
+ def test_dev_path_accepts_uppercase_extension(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ src = temp_dir / "Sample.YAML"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", "--dev", str(src)])
+
+ # Before the fix the --dev branch rejects ".YAML" with
+ # "--dev source must be a workflow YAML file ...".
+ assert result.exit_code == 0, result.output
+ assert "installed" in result.output
+
+ def test_lowercase_extension_still_installs(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ """Happy path (lowercase .yml) is unchanged by the case-normalization."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ src = temp_dir / "sample.yml"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code == 0, result.output
+ assert "installed" in result.output
+
+ def test_add_installs_workflow_with_custom_step(self, temp_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ step_dir = temp_dir / ".specify" / "workflows" / "steps" / "test-add-step"
+ step_dir.mkdir(parents=True)
+ step_manifest = {
+ "schema_version": "1.0",
+ "step": {
+ "type_key": "test-add-step",
+ "name": "Test Add Step",
+ "version": "1.0.0",
+ },
+ }
+ (step_dir / "step.yml").write_text(
+ yaml.safe_dump(step_manifest, sort_keys=False),
+ encoding="utf-8",
+ )
+ (step_dir / "__init__.py").write_text(
+ """
+from specify_cli.workflows.base import StepBase, StepResult
+
+
+class TestAddStep(StepBase):
+ type_key = "test-add-step"
+
+ def execute(self, config, context):
+ return StepResult()
+""",
+ encoding="utf-8",
+ )
+
+ src = temp_dir / "sample.yml"
+ workflow_definition = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "test-workflow-with-custom-step",
+ "name": "Test Workflow With Custom Step",
+ "version": "1.0.0",
+ },
+ "steps": [
+ {"id": "custom-step", "type": "test-add-step"},
+ ],
+ }
+ src.write_text(
+ yaml.safe_dump(workflow_definition, sort_keys=False),
+ encoding="utf-8",
+ )
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code == 0, result.output
+ installed_workflow = (
+ temp_dir
+ / ".specify"
+ / "workflows"
+ / "test-workflow-with-custom-step"
+ / "workflow.yml"
+ )
+ assert installed_workflow.is_file()
+
+
+
+class TestWorkflowAddUrlResolution:
+ """CLI-level tests for workflow add <url> GitHub release URL resolution."""
+
+ VALID_WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "test-wf"
+ name: "Test Workflow"
+ version: "1.0.0"
+ description: "A test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def test_workflow_add_from_github_release_url_resolves_and_downloads(self, project_dir):
+ """'workflow add <github-release-url>' resolves to API asset URL."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ captured_urls = []
+
+ class FakeResponse:
+ def __init__(self, data, url=None):
+ self._data = data
+ self._pos = 0
+ self._url = url or "https://api.github.com/repos/org/repo/releases/assets/42"
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self._data) - self._pos
+ out = self._data[self._pos : self._pos + size]
+ self._pos += len(out)
+ return out
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ captured_urls.append(
+ (url, extra_headers, timeout, redirect_validator)
+ )
+ if "releases/tags/" in url:
+ return FakeResponse(json.dumps({
+ "assets": [{"name": "workflow.yml", "url": "https://api.github.com/repos/org/repo/releases/assets/42"}]
+ }).encode())
+ return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir), \
+ patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
+ result = runner.invoke(app, [
+ "workflow", "add",
+ "https://github.com/org/repo/releases/download/v1.0/workflow.yml",
+ ])
+
+ assert result.exit_code == 0, result.output
+ assert "Test Workflow" in result.output
+ # First call resolves the release tag with timeout=30
+ tag_calls = [
+ (url, headers, timeout, validator)
+ for url, headers, timeout, validator in captured_urls
+ if "releases/tags/" in url
+ ]
+ assert len(tag_calls) == 1
+ assert tag_calls[0][2] == 30 # timeout matches download timeout
+ assert tag_calls[0][3] is not None
+ # Second call downloads from the resolved asset URL with octet-stream
+ asset_calls = [
+ (url, headers, timeout, validator)
+ for url, headers, timeout, validator in captured_urls
+ if "releases/assets/" in url
+ ]
+ assert len(asset_calls) >= 1
+ assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
+
+ def test_workflow_add_from_direct_api_asset_url_passes_through(self, project_dir):
+ """'workflow add <api-asset-url>' uses URL directly with octet-stream."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ captured_urls = []
+
+ class FakeResponse:
+ def __init__(self, data, url=None):
+ self._data = data
+ self._pos = 0
+ self._url = url or "https://api.github.com/repos/org/repo/releases/assets/42"
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self._data) - self._pos
+ out = self._data[self._pos : self._pos + size]
+ self._pos += len(out)
+ return out
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ captured_urls.append((url, extra_headers))
+ return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir), \
+ patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
+ result = runner.invoke(app, [
+ "workflow", "add",
+ "https://api.github.com/repos/org/repo/releases/assets/42",
+ ])
+
+ assert result.exit_code == 0, result.output
+ # Should go directly to the asset URL with Accept header
+ assert len(captured_urls) == 1
+ assert captured_urls[0][0] == "https://api.github.com/repos/org/repo/releases/assets/42"
+ assert captured_urls[0][1] == {"Accept": "application/octet-stream"}
+
+ def test_workflow_add_catalog_based_resolves_github_release_url(self, project_dir):
+ """'workflow add <id>' with catalog GitHub release URL resolves via API."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ captured_urls = []
+
+ class FakeResponse:
+ def __init__(self, data, url=None):
+ self._data = data
+ self._pos = 0
+ self._url = url or "https://api.github.com/repos/org/repo/releases/assets/55"
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self._data) - self._pos
+ out = self._data[self._pos : self._pos + size]
+ self._pos += len(out)
+ return out
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ captured_urls.append((url, extra_headers, redirect_validator))
+ if "releases/tags/" in url:
+ return FakeResponse(json.dumps({
+ "assets": [{"name": "workflow.yml", "url": "https://api.github.com/repos/org/repo/releases/assets/55"}]
+ }).encode())
+ # Use workflow YAML with id matching catalog key
+ wf_yaml = """
+schema_version: "1.0"
+workflow:
+ id: "my-wf"
+ name: "My Workflow"
+ version: "1.0.0"
+ description: "A catalog workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+ return FakeResponse(wf_yaml.encode())
+
+ fake_catalog_info = {
+ "id": "my-wf",
+ "name": "My Workflow",
+ "version": "1.0.0",
+ "url": "https://github.com/org/repo/releases/download/v2.0/workflow.yml",
+ "_install_allowed": True,
+ }
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir), \
+ patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url), \
+ patch("specify_cli.workflows.catalog.WorkflowCatalog.get_workflow_info", return_value=fake_catalog_info):
+ result = runner.invoke(app, ["workflow", "add", "my-wf"])
+
+ assert result.exit_code == 0, result.output
+ # Should resolve via releases/tags API
+ tag_calls = [
+ (url, validator)
+ for url, _, validator in captured_urls
+ if "releases/tags/" in url
+ ]
+ assert len(tag_calls) == 1
+ assert "releases/tags/v2.0" in tag_calls[0][0]
+ assert tag_calls[0][1] is not None
+ # Should download from resolved asset URL with octet-stream
+ asset_calls = [
+ (url, headers)
+ for url, headers, _ in captured_urls
+ if "releases/assets/" in url
+ ]
+ assert len(asset_calls) >= 1
+ assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
+
+ def test_workflow_add_from_ghes_release_url_resolves_via_api_v3(self, project_dir, monkeypatch):
+ """'workflow add <ghes-release-url>' resolves via GHES /api/v3 endpoint."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+ from specify_cli.authentication import http as _auth_http
+ from specify_cli.authentication.config import AuthConfigEntry
+
+ monkeypatch.setattr(_auth_http, "_config_override", [
+ AuthConfigEntry(hosts=("ghes.example",), provider="github", auth="bearer", token="t"),
+ ])
+
+ captured_urls = []
+
+ class FakeResponse:
+ def __init__(self, data, url=None):
+ self._data = data
+ self._pos = 0
+ self._url = url or "https://ghes.example/api/v3/repos/org/repo/releases/assets/42"
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self._data) - self._pos
+ out = self._data[self._pos : self._pos + size]
+ self._pos += len(out)
+ return out
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ captured_urls.append((url, extra_headers))
+ if "releases/tags/" in url:
+ return FakeResponse(json.dumps({
+ "assets": [{"name": "workflow.yml", "url": "https://ghes.example/api/v3/repos/org/repo/releases/assets/42"}]
+ }).encode())
+ return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir), \
+ patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
+ result = runner.invoke(app, [
+ "workflow", "add",
+ "https://ghes.example/org/repo/releases/download/v1.0/workflow.yml",
+ ])
+
+ assert result.exit_code == 0, result.output
+ # Tag lookup must use the GHES /api/v3 endpoint
+ assert any("ghes.example/api/v3/repos/org/repo/releases/tags/v1.0" in url for url, _ in captured_urls)
+ # Asset download must carry Accept: application/octet-stream
+ asset_calls = [(url, h) for url, h in captured_urls if "releases/assets/" in url]
+ assert len(asset_calls) >= 1
+ assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
+
+ def test_workflow_add_catalog_based_ghes_release_url_resolves_via_api_v3(self, project_dir, monkeypatch):
+ """'workflow add <id>' with a GHES catalog URL resolves via /api/v3."""
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+ from specify_cli.authentication import http as _auth_http
+ from specify_cli.authentication.config import AuthConfigEntry
+
+ monkeypatch.setattr(_auth_http, "_config_override", [
+ AuthConfigEntry(hosts=("ghes.example",), provider="github", auth="bearer", token="t"),
+ ])
+
+ captured_urls = []
+
+ class FakeResponse:
+ def __init__(self, data, url=None):
+ self._data = data
+ self._pos = 0
+ self._url = url or "https://ghes.example/api/v3/repos/org/repo/releases/assets/55"
+
+ def read(self, size=-1):
+ if size < 0:
+ size = len(self._data) - self._pos
+ out = self._data[self._pos : self._pos + size]
+ self._pos += len(out)
+ return out
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ ghes_wf_yaml = """
+schema_version: "1.0"
+workflow:
+ id: "my-wf"
+ name: "My GHES Workflow"
+ version: "1.0.0"
+ description: "A GHES catalog workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ captured_urls.append((url, extra_headers))
+ if "releases/tags/" in url:
+ return FakeResponse(json.dumps({
+ "assets": [{"name": "workflow.yml", "url": "https://ghes.example/api/v3/repos/org/repo/releases/assets/55"}]
+ }).encode())
+ return FakeResponse(ghes_wf_yaml.encode())
+
+ fake_catalog_info = {
+ "id": "my-wf",
+ "name": "My GHES Workflow",
+ "version": "1.0.0",
+ "url": "https://ghes.example/org/repo/releases/download/v2.0/workflow.yml",
+ "_install_allowed": True,
+ }
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir), \
+ patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url), \
+ patch("specify_cli.workflows.catalog.WorkflowCatalog.get_workflow_info", return_value=fake_catalog_info):
+ result = runner.invoke(app, ["workflow", "add", "my-wf"])
+
+ assert result.exit_code == 0, result.output
+ # Tag lookup must use GHES /api/v3
+ tag_calls = [url for url, _ in captured_urls if "releases/tags/" in url]
+ assert len(tag_calls) == 1
+ assert "ghes.example/api/v3/repos/org/repo/releases/tags/v2.0" in tag_calls[0]
+ # Asset download must carry Accept: application/octet-stream
+ asset_calls = [(url, h) for url, h in captured_urls if "releases/assets/" in url]
+ assert len(asset_calls) >= 1
+ assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
+
+
+
+class TestWorkflowAddNonStringScalars:
+ """`workflow add` reports clean errors for non-string YAML scalars (#3420)."""
+
+ @pytest.mark.parametrize(
+ ("field_yaml", "expected"),
+ [
+ ('id: 123\n name: "Probe"\n version: "1.0.0"', "workflow.id"),
+ ('id: "probe"\n name: "Probe"\n version: 1.0', "workflow.version"),
+ ],
+ )
+ def test_add_reports_validation_error_not_traceback(
+ self, project_dir, monkeypatch, field_yaml, expected
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ wf = project_dir / "workflow.yml"
+ wf.write_text(
+ "schema_version: \"1.0\"\n"
+ f"workflow:\n {field_yaml}\n"
+ "steps:\n - id: s1\n type: shell\n run: \"echo hi\"\n",
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(wf)])
+ assert result.exit_code == 1
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert expected in result.output
+
+ def test_add_non_string_step_id_reports_validation_error(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ wf = project_dir / "workflow.yml"
+ wf.write_text(
+ "workflow:\n id: \"probe\"\n name: \"Probe\"\n version: \"1.0.0\"\n"
+ "steps:\n - id: 123\n type: shell\n run: \"echo hi\"\n",
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(wf)])
+ assert result.exit_code == 1
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Step ID" in result.output
+
+
+
+class TestWorkflowAddSymlinkGuard:
+ def test_add_malformed_ipv6_url_exits_cleanly(self, temp_dir, monkeypatch):
+ """A malformed IPv6 URL must produce a clean error, not a ValueError traceback."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify").mkdir(exist_ok=True)
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(
+ app,
+ ["workflow", "add", "https://[::1/wf.yaml"],
+ catch_exceptions=True,
+ )
+
+ assert result.exit_code == 1
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Invalid URL" in result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_add_refuses_symlinked_specify(self, temp_dir, monkeypatch):
+ """workflow add must refuse a symlinked .specify (writes could escape root)."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ outside = temp_dir.parent / "outside-specify-target"
+ (outside / "workflows").mkdir(parents=True, exist_ok=True)
+ (temp_dir / ".specify").symlink_to(outside, target_is_directory=True)
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", "anything.yml"])
+
+ assert result.exit_code != 0
+ assert "symlinked .specify" in result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_add_refuses_symlinked_workflows_dir(self, temp_dir, monkeypatch):
+ """workflow add must refuse a symlinked .specify/workflows directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify").mkdir()
+ outside = temp_dir.parent / "outside-workflows-target"
+ outside.mkdir(parents=True, exist_ok=True)
+ (temp_dir / ".specify" / "workflows").symlink_to(outside, target_is_directory=True)
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", "anything.yml"])
+
+ assert result.exit_code != 0
+ assert "symlinked .specify/workflows" in result.output
+
+ def test_add_escapes_rich_markup_in_validation_errors(self, temp_dir, monkeypatch):
+ """User-controlled YAML values in validation errors must not be parsed as Rich markup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ src = temp_dir / "incoming.yml"
+ src.write_text(
+ """
+schema_version: "1.0"
+workflow:
+ id: "markup-wf"
+ name: "Markup"
+ version: "[bold]bad[/bold]"
+
+steps:
+ - id: step-one
+ command: speckit.specify
+""",
+ encoding="utf-8",
+ )
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code != 0
+ assert "[bold]bad[/bold]" in result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_add_refuses_symlinked_id_dir(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ """A symlinked <id> install dir must not let a copy escape the project root."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ outside = temp_dir.parent / "outside-id-target"
+ outside.mkdir(parents=True, exist_ok=True)
+ # <id> from the YAML below is "test-workflow"; plant it as a symlink.
+ (temp_dir / ".specify" / "workflows" / "test-workflow").symlink_to(
+ outside, target_is_directory=True
+ )
+ src = temp_dir / "incoming.yml"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code != 0
+ # No write-through: the symlink target stays empty.
+ assert not (outside / "workflow.yml").exists()
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_add_refuses_symlinked_workflow_yml_leaf(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ """A symlinked <id>/workflow.yml must not let copy2 write through the link."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ id_dir = temp_dir / ".specify" / "workflows" / "test-workflow"
+ id_dir.mkdir(parents=True)
+ outside_file = temp_dir.parent / "outside-leaf-target.yml"
+ outside_file.write_text("original\n", encoding="utf-8")
+ (id_dir / "workflow.yml").symlink_to(outside_file)
+ src = temp_dir / "incoming.yml"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code != 0
+ # Rich may wrap the message; assert on the unbroken path fragment.
+ assert "test-workflow/workflow.yml" in result.output
+ assert "symlinked" in result.output
+ # The link target content is untouched.
+ assert outside_file.read_text(encoding="utf-8") == "original\n"
+
+ def test_add_refuses_non_directory_id(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ """An <id> path that already exists as a file must fail cleanly, not crash."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ wf_dir = temp_dir / ".specify" / "workflows"
+ wf_dir.mkdir(parents=True)
+ (wf_dir / "test-workflow").write_text("not a dir", encoding="utf-8")
+ src = temp_dir / "incoming.yml"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code != 0
+ assert "exists but is not a directory" in result.output
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+
+ def test_add_refuses_workflow_yml_as_directory(self, temp_dir, monkeypatch, sample_workflow_yaml):
+ """A pre-existing <id>/workflow.yml *directory* must fail cleanly, not crash."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ id_dir = temp_dir / ".specify" / "workflows" / "test-workflow"
+ id_dir.mkdir(parents=True)
+ # Plant workflow.yml as a directory so a later write/copy2 would raise
+ # IsADirectoryError without the explicit non-file guard.
+ (id_dir / "workflow.yml").mkdir()
+ src = temp_dir / "incoming.yml"
+ src.write_text(sample_workflow_yaml, encoding="utf-8")
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(src)])
+
+ assert result.exit_code != 0
+ assert "test-workflow/workflow.yml" in result.output
+ assert "is not a file" in result.output
+ # Clean exit, not an unhandled IsADirectoryError traceback.
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+
+ def test_safe_workflow_id_dir_escapes_markup_in_invalid_id(self, temp_dir, capsys):
+ """A traversal <id> carrying Rich markup must be escaped, not interpreted."""
+ from specify_cli.workflows._commands import _safe_workflow_id_dir
+
+ workflows_dir = temp_dir / ".specify" / "workflows"
+ workflows_dir.mkdir(parents=True)
+ # Traversal (so the "Invalid workflow ID" branch fires) plus markup.
+ with pytest.raises(typer.Exit):
+ _safe_workflow_id_dir(workflows_dir, "../[red]evil[/red]")
+
+ out = capsys.readouterr().out
+ # Literal bracketed text survives; Rich did not consume it as a tag.
+ assert "[red]evil[/red]" in out
+
+ def test_add_rejects_reserved_overlay_storage_id(self, temp_dir, monkeypatch):
+ """workflow add must not install into the overlay storage directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ overlay_file = temp_dir / "incoming.yml"
+ overlay_file.write_text(
+ """
+schema_version: "1.0"
+workflow:
+ id: "overlays"
+ name: "Bad Workflow"
+ version: "1.0.0"
+steps:
+ - id: step-one
+ command: speckit.specify
+""".strip()
+ + "\n",
+ encoding="utf-8",
+ )
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "add", str(overlay_file)])
+
+ assert result.exit_code != 0
+ assert "Invalid workflow ID" in result.output
+ assert not (temp_dir / ".specify" / "workflows" / "overlays" / "workflow.yml").exists()
+
+ @pytest.mark.parametrize(
+ "workflow_id",
+ [
+ "overlays",
+ "runs",
+ "steps",
+ "nested/workflow",
+ "nested\\workflow",
+ "bad id",
+ " bad-id",
+ "bad-id ",
+ ],
+ )
+ def test_safe_workflow_id_dir_rejects_reserved_or_non_segment_ids(
+ self, temp_dir, workflow_id, capsys
+ ):
+ """Install IDs must not collide with workflow internals or create nested paths."""
+ from specify_cli.workflows._commands import _safe_workflow_id_dir
+
+ workflows_dir = temp_dir / ".specify" / "workflows"
+ workflows_dir.mkdir(parents=True)
+
+ with pytest.raises(typer.Exit):
+ _safe_workflow_id_dir(workflows_dir, workflow_id)
+
+ assert "Invalid workflow ID" in capsys.readouterr().out
+ assert not (workflows_dir / workflow_id).exists()
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _archive_workflow_dir(self, source_dir, archive_path, nested=False):
+ prefix = Path("align-wf-v1") if nested else Path()
+ if archive_path.name.lower().endswith(".zip"):
+ with zipfile.ZipFile(archive_path, "w") as archive:
+ for file_path in source_dir.rglob("*"):
+ if file_path.is_file():
+ archive.write(
+ file_path,
+ prefix / file_path.relative_to(source_dir),
+ )
+ else:
+ with tarfile.open(archive_path, "w:gz") as archive:
+ for file_path in source_dir.rglob("*"):
+ if file_path.is_file():
+ archive.add(
+ file_path,
+ arcname=prefix / file_path.relative_to(source_dir),
+ )
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ class _FakeResponse:
+ def __init__(self, data, url="https://example.com/workflow.yml", headers=None):
+ self._data = data
+ self._url = url
+ self._pos = 0
+ self._headers = headers or {}
+
+ def read(self, amt=None):
+ if amt is None:
+ chunk = self._data[self._pos :]
+ self._pos = len(self._data)
+ return chunk
+ chunk = self._data[self._pos : self._pos + amt]
+ self._pos += len(chunk)
+ return chunk
+
+ def getheader(self, name, default=None):
+ return self._headers.get(name, default)
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def test_add_dev_directory_installs(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+ assert WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_local_directory_preserves_package_files(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "scripts").mkdir()
+ (source / "scripts" / "helper.sh").write_text("echo helper\n")
+
+ result = CliRunner().invoke(app, ["workflow", "add", str(source)])
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (installed / "scripts" / "helper.sh").read_text() == "echo helper\n"
+
+ @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
+ @pytest.mark.parametrize("nested", [False, True])
+ def test_add_local_archive_preserves_package_files(
+ self, project_dir, monkeypatch, suffix, nested
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "assets").mkdir()
+ (source / "assets" / "message.txt").write_text("hello\n")
+ archive_path = project_dir / f"align-wf{suffix}"
+ self._archive_workflow_dir(source, archive_path, nested=nested)
+
+ result = CliRunner().invoke(app, ["workflow", "add", str(archive_path)])
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (installed / "assets" / "message.txt").read_text() == "hello\n"
+
+ def test_add_dev_yaml_file_installs(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ src = self._write_workflow_dir(project_dir)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(src / "workflow.yml"), "--dev"])
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_dev_missing_path_errors(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(project_dir / "missing"), "--dev"])
+ assert result.exit_code != 0
+ assert "--dev" in result.output
+
+ def test_add_dev_dir_without_workflow_yml_errors(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ empty = project_dir / "empty-src"
+ empty.mkdir()
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(empty), "--dev"])
+ assert result.exit_code != 0
+ assert "No workflow.yml found" in result.output
+
+ def test_add_local_dir_without_workflow_yml_errors(self, project_dir, monkeypatch):
+ """Same as the --dev case, but for the plain local-path fallback (no --dev)."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ empty = project_dir / "empty-src-[bracket]"
+ empty.mkdir()
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(empty)])
+ assert result.exit_code != 0
+ assert "No workflow.yml found" in result.output
+ assert "[bracket]" in result.output
+
+ def test_add_local_dir_with_workflow_yml_directory_errors_cleanly(self, project_dir, monkeypatch):
+ """Same as the --dev case, but for the plain local-path fallback (no --dev):
+ a directory named workflow.yml must not reach open() and leak IsADirectoryError."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ src_dir = project_dir / "local-wf"
+ (src_dir / "workflow.yml").mkdir(parents=True)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", str(src_dir)])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "No workflow.yml found" in result.output
+
+ def test_add_yaml_parse_error_escapes_rich_markup(self, project_dir, monkeypatch):
+ """A YAML syntax error can quote the offending line verbatim; brackets in it must not be Rich markup."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ monkeypatch.chdir(project_dir)
+ bad = project_dir / "bad.yml"
+ bad.write_text("workflow:\n id: wf\n", encoding="utf-8")
+ runner = CliRunner()
+ with patch.object(
+ WorkflowDefinition,
+ "from_string",
+ side_effect=ValueError('bad snippet: "New [Feature]"'),
+ ):
+ result = runner.invoke(app, ["workflow", "add", str(bad)])
+ assert result.exit_code != 0
+ assert 'bad snippet: "New [Feature]"' in result.output
+
+ @pytest.mark.parametrize("mode", ["dev", "local", "from"])
+ def test_reinstall_preserves_disabled_state(
+ self, project_dir, monkeypatch, mode
+ ):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ if mode == "dev":
+ result = runner.invoke(
+ app, ["workflow", "add", str(src), "--dev"]
+ )
+ elif mode == "local":
+ result = runner.invoke(app, ["workflow", "add", str(src)])
+ else:
+ data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(
+ app,
+ [
+ "workflow", "add", "align-wf",
+ "--from", "https://example.com/workflow.yml",
+ ],
+ input="y\n",
+ )
+
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
+
+ def test_add_from_url_rejects_oversized_content_length(self, project_dir, monkeypatch):
+ """A --from download must not trust an advertised Content-Length
+ alone by reading the whole body first -- it must reject a response
+ that declares a size over the workflow YAML limit before reading
+ the (potentially huge) body into memory at all."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ small_body = b"id: align-wf\n" # small actual body; Content-Length lies
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ small_body, url, headers={"Content-Length": "1000"}
+ ),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
+
+ def test_add_from_url_requires_default_deny_confirmation(
+ self, project_dir, monkeypatch
+ ):
+ from unittest.mock import patch
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=AssertionError("download should not start"),
+ ):
+ result = CliRunner().invoke(
+ app,
+ [
+ "workflow",
+ "add",
+ "align-wf",
+ "--from",
+ "https://example.com/workflow.yml",
+ ],
+ input="n\n",
+ )
+
+ assert result.exit_code == 0, result.output
+ assert "Untrusted Source" in result.output
+ assert "Cancelled" in result.output
+
+ def test_add_from_url_rejects_oversized_streamed_body_without_content_length(
+ self, project_dir, monkeypatch
+ ):
+ """A chunked/no-Content-Length response must still be capped by
+ actually counting streamed bytes -- a malicious or misbehaving
+ server cannot bypass the limit merely by omitting or lying about
+ Content-Length."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ oversized_body = b"x" * 500 # no Content-Length header at all
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ oversized_body, url
+ ),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
+
+ def test_add_from_url_oversized_streamed_body_leaves_no_temp_file(
+ self, project_dir, monkeypatch, tmp_path
+ ):
+ """A rejected --from download (oversized streamed body, no
+ Content-Length) must not leave the 0-byte NamedTemporaryFile behind:
+ the file is created on disk as soon as it is opened (delete=False),
+ before any bytes are written, so a failure inside the size-limit
+ check must still clean it up rather than merely erroring out."""
+ import tempfile as tempfile_mod
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ scratch_tmp = tmp_path / "scratch-tmp"
+ scratch_tmp.mkdir()
+ monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
+ oversized_body = b"x" * 500 # no Content-Length header at all
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ oversized_body, url
+ ),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
+ leaked = list(scratch_tmp.glob("*.yml"))
+ assert leaked == [], f"leaked temp files: {leaked}"
+
+ def test_add_from_url_interrupt_during_read_leaves_no_temp_file(
+ self, project_dir, monkeypatch, tmp_path
+ ):
+ """A KeyboardInterrupt while streaming the response body must still
+ unlink the already-created (delete=False) temp file. Unlike a
+ download ``ValueError``, ``KeyboardInterrupt`` is a ``BaseException``
+ and is not caught by ``except Exception`` -- only a ``BaseException``
+ handler around the temp-file lifetime can clean it up."""
+ import tempfile as tempfile_mod
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+
+ monkeypatch.chdir(project_dir)
+ scratch_tmp = tmp_path / "scratch-tmp"
+ scratch_tmp.mkdir()
+ monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
+
+ def _boom(*args, **kwargs):
+ raise KeyboardInterrupt()
+
+ monkeypatch.setattr(wf_commands, "_read_response_within_limit", _boom)
+ body = b"id: align-wf\n"
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ body, url
+ ),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ leaked = list(scratch_tmp.glob("*.yml"))
+ assert leaked == [], f"leaked temp files: {leaked}"
+
+ def test_add_from_url_oversized_content_length_leaves_no_temp_file(
+ self, project_dir, monkeypatch, tmp_path
+ ):
+ """Same guarantee for the fail-fast Content-Length rejection path:
+ it must not even leave a 0-byte temp file behind."""
+ import tempfile as tempfile_mod
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ scratch_tmp = tmp_path / "scratch-tmp"
+ scratch_tmp.mkdir()
+ monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
+ small_body = b"id: align-wf\n" # small actual body; Content-Length lies
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ small_body, url, headers={"Content-Length": "1000"}
+ ),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
+ leaked = list(scratch_tmp.glob("*.yml"))
+ assert leaked == [], f"leaked temp files: {leaked}"
+
+ def test_add_from_url_download_failure_cleanup_error_preserves_original_error(
+ self, project_dir, monkeypatch, tmp_path
+ ):
+ """The --from download-failure branch's `tmp_path.unlink(missing_ok=
+ True)` can itself raise (e.g. read-only tempdir) before the clean
+ "Failed to download workflow" message is ever printed, replacing it
+ with a raw unhandled OSError. A cleanup failure there must be
+ guarded exactly like the later post-install finally cleanup: warn
+ about the cleanup failure, then still preserve/report the original
+ download error via a clean typer.Exit, never a raw traceback."""
+ import tempfile as tempfile_mod
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ scratch_tmp = tmp_path / "scratch-tmp"
+ scratch_tmp.mkdir()
+ monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
+ oversized_body = b"x" * 500 # no Content-Length header at all
+ runner = CliRunner()
+
+ real_unlink = Path.unlink
+
+ def unlink_boom(self_path, *args, **kwargs):
+ if self_path.suffix == ".yml" and self_path.parent == scratch_tmp:
+ raise OSError("cleanup denied")
+ return real_unlink(self_path, *args, **kwargs)
+
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ oversized_body, url
+ ),
+ ), pytest.MonkeyPatch.context() as mp:
+ mp.setattr(Path, "unlink", unlink_boom)
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ # Original download error remains present. Normalize whitespace so the
+ # assertion is robust to Rich line-wrapping at narrow terminal widths.
+ normalized_output = "".join(result.output.split())
+ assert "exceedsthe100-byteworkflowsizelimit" in normalized_output
+ # Cleanup failure is reported too, not silently swallowed / crashing.
+ assert "cleanupdenied" in normalized_output
+ assert "Warning" in result.output
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_from_url_installs(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
+ def test_add_from_url_installs_complete_archive_package(
+ self, project_dir, monkeypatch, suffix
+ ):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "assets").mkdir()
+ (source / "assets" / "remote.txt").write_text("remote\n")
+ archive_path = project_dir / f"remote{suffix}"
+ self._archive_workflow_dir(source, archive_path)
+ data = archive_path.read_bytes()
+ url = f"https://example.com/align-wf{suffix}"
+
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda *_args, **_kwargs: self._FakeResponse(data, url),
+ ):
+ result = CliRunner().invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", url],
+ input="y\n",
+ )
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (installed / "assets" / "remote.txt").read_text() == "remote\n"
+
+ @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
+ def test_add_from_suffixless_url_sniffs_archive(
+ self, project_dir, monkeypatch, suffix
+ ):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "assets").mkdir()
+ (source / "assets" / "sniffed.txt").write_text("sniffed\n")
+ archive_path = project_dir / f"remote{suffix}"
+ self._archive_workflow_dir(source, archive_path)
+ data = archive_path.read_bytes()
+ url = "https://example.com/assets/12345"
+
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda *_args, **_kwargs: self._FakeResponse(
+ data,
+ url,
+ {"Content-Type": "application/octet-stream"},
+ ),
+ ):
+ result = CliRunner().invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", url],
+ input="y\n",
+ )
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (installed / "assets" / "sniffed.txt").read_text() == "sniffed\n"
+
+ @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
+ def test_add_catalog_installs_complete_archive_package_and_sha(
+ self, project_dir, monkeypatch, suffix
+ ):
+ import hashlib
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "assets").mkdir()
+ (source / "assets" / "catalog.txt").write_text("catalog\n")
+ archive_path = project_dir / f"catalog{suffix}"
+ self._archive_workflow_dir(source, archive_path, nested=True)
+ data = archive_path.read_bytes()
+ url = f"https://example.com/align-wf{suffix}"
+ info = {
+ "id": "align-wf",
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": url,
+ "sha256": hashlib.sha256(data).hexdigest(),
+ "_install_allowed": True,
+ "_catalog_name": "test",
+ }
+
+ with patch.object(
+ WorkflowCatalog,
+ "get_workflow_info",
+ return_value=info,
+ ), patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda *_args, **_kwargs: self._FakeResponse(data, url),
+ ):
+ result = CliRunner().invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (installed / "assets" / "catalog.txt").read_text() == "catalog\n"
+
+ @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
+ def test_add_catalog_sniffs_suffixless_archive(
+ self, project_dir, monkeypatch, suffix
+ ):
+ import hashlib
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ (source / "assets").mkdir()
+ (source / "assets" / "sniffed.txt").write_text("catalog sniffed\n")
+ archive_path = project_dir / f"catalog{suffix}"
+ self._archive_workflow_dir(source, archive_path, nested=True)
+ data = archive_path.read_bytes()
+ url = "https://example.com/assets/67890"
+ info = {
+ "id": "align-wf",
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": url,
+ "sha256": hashlib.sha256(data).hexdigest(),
+ "_install_allowed": True,
+ "_catalog_name": "test",
+ }
+
+ with patch.object(
+ WorkflowCatalog,
+ "get_workflow_info",
+ return_value=info,
+ ), patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda *_args, **_kwargs: self._FakeResponse(
+ data,
+ url,
+ {"Content-Type": "application/octet-stream"},
+ ),
+ ):
+ result = CliRunner().invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code == 0, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert (
+ installed / "assets" / "sniffed.txt"
+ ).read_text() == "catalog sniffed\n"
+
+ def test_package_registry_failure_restores_before_failed_cleanup(
+ self, project_dir, monkeypatch
+ ):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir, version="1.0.0")
+ (source / "assets").mkdir()
+ (source / "assets" / "version.txt").write_text("old\n")
+ runner = CliRunner()
+ first = runner.invoke(app, ["workflow", "add", str(source)])
+ assert first.exit_code == 0, first.output
+
+ (source / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"),
+ encoding="utf-8",
+ )
+ (source / "assets" / "version.txt").write_text("new\n")
+ real_rmtree = shutil.rmtree
+
+ def fail_failed_package_cleanup(path, *args, **kwargs):
+ if ".failed-" in Path(path).name:
+ raise OSError("cleanup denied")
+ return real_rmtree(path, *args, **kwargs)
+
+ with patch.object(
+ WorkflowRegistry,
+ "add",
+ side_effect=OSError("registry save failed"),
+ ), patch(
+ "shutil.rmtree",
+ side_effect=fail_failed_package_cleanup,
+ ):
+ result = runner.invoke(app, ["workflow", "add", str(source)])
+
+ assert result.exit_code == 1, result.output
+ installed = project_dir / ".specify" / "workflows" / "align-wf"
+ assert "1.0.0" in (installed / "workflow.yml").read_text()
+ assert (installed / "assets" / "version.txt").read_text() == "old\n"
+ assert "registry save failed" in result.output
+ assert "cleanup denied" in result.output
+
+ def test_add_from_url_temp_cleanup_failure_after_success_still_exits_zero(
+ self, project_dir, monkeypatch
+ ):
+ """An OSError while deleting the --from download's temp file after
+ _validate_and_install_local() has already committed the file and
+ registry entry must not surface as an unhandled failure for an
+ install that already succeeded -- it must be a warning, exit 0."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+
+
+ real_unlink = Path.unlink
+
+ def unlink_boom(self_path, *args, **kwargs):
+ if self_path.suffix == ".yml" and self_path.parent == Path(tempfile.gettempdir()):
+ raise OSError("permission denied")
+ return real_unlink(self_path, *args, **kwargs)
+
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ), pytest.MonkeyPatch.context() as mp:
+ mp.setattr(Path, "unlink", unlink_boom)
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+
+ assert result.exit_code == 0, result.output
+ assert "Warning" in result.output
+ assert "permissiondenied" in "".join(result.output.split())
+ assert WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_from_url_id_mismatch_errors(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "other-id", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert "does not match" in result.output
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_from_empty_url_rejected_not_catalog_fallback(self, project_dir, monkeypatch):
+ """--from "" must fail URL validation, not silently install from the catalog."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", "align-wf", "--from", ""])
+ assert result.exit_code != 0
+ assert "HTTPS" in result.output
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_from_url_non_https_redirect_escapes_rich_markup(self, project_dir, monkeypatch):
+ """A redirect to a non-HTTPS IPv6 literal (legally bracketed) must not be parsed as Rich markup."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ redirected_url = "http://[2001:db8::1]/workflow.yml"
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(b"", redirected_url),
+ ):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code != 0
+ assert redirected_url in result.output
+
+ def test_add_from_rejects_invalid_source_id_without_fetch(self, project_dir, monkeypatch):
+ """--from with a non-workflow-id source (URL, path, uppercase) fails before any network fetch."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ calls: list[str] = []
+
+ def _fake_open(url, timeout=None, extra_headers=None, redirect_validator=None):
+ calls.append(url)
+ raise AssertionError(f"network fetch attempted: {url}")
+
+ runner = CliRunner()
+ with patch("specify_cli.authentication.http.open_url", side_effect=_fake_open):
+ for bad_source in ("https://x/y.yml", "./local.yml", "BadCase"):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", bad_source, "--from", "https://example.com/workflow.yml"],
+ )
+ assert result.exit_code != 0
+ assert "Invalid workflow ID" in result.output
+ assert calls == []
+
+ def test_add_dev_dir_with_workflow_yml_directory_errors_cleanly(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ dev_dir = project_dir / "dev-wf"
+ (dev_dir / "workflow.yml").mkdir(parents=True)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", "--dev", str(dev_dir)])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "No workflow.yml found" in result.output
+
+ @pytest.mark.parametrize("mode", ["dev", "local", "from_url"])
+ def test_add_save_failure_leaves_no_orphan_directory(self, project_dir, monkeypatch, mode):
+ """A registry.add() save failure during a fresh install must not leave
+ an orphaned workflow directory on disk, and must fail with a clean
+ escaped message instead of a raw OSError traceback. Shared by --dev,
+ the plain local-path fallback, and --from since all three funnel
+ through _validate_and_install_local's single install choke point."""
+ import contextlib
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+
+ def boom(self):
+ raise OSError("disk full")
+
+ if mode == "from_url":
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ args = ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"]
+ url_patch = patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ )
+ else:
+ src = self._write_workflow_dir(project_dir)
+ args = ["workflow", "add", str(src)] + (["--dev"] if mode == "dev" else [])
+ url_patch = contextlib.nullcontext()
+
+ with url_patch, pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(
+ app, args, input="y\n" if mode == "from_url" else None
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists()
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ @pytest.mark.parametrize("mode", ["dev", "catalog"])
+ def test_add_non_json_description_rolls_back_transaction(
+ self, project_dir, monkeypatch, mode
+ ):
+ import contextlib
+ from unittest.mock import patch
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ data = self.WORKFLOW_YAML.format(version="1.0.0").replace(
+ 'description: "CLI alignment test workflow"',
+ "description: 2026-01-02",
+ ).encode()
+
+ if mode == "dev":
+ source = project_dir / "dated-description"
+ source.mkdir()
+ (source / "workflow.yml").write_bytes(data)
+ args = ["workflow", "add", str(source), "--dev"]
+ download = contextlib.nullcontext()
+ else:
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ args = ["workflow", "add", "align-wf"]
+ download = patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ )
+
+ with download:
+ result = CliRunner().invoke(app, args)
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Failed to update workflow registry" in result.output
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists()
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ @pytest.mark.parametrize("mode", ["dev", "local", "from_url"])
+ def test_add_fresh_install_mkstemp_failure_leaves_no_orphan_directory(
+ self, project_dir, monkeypatch, mode
+ ):
+ """_stage_workflow_file() does mkdir(dest_dir) then mkstemp() inside
+ it. For a fresh install (no prior directory), if mkdir succeeds but
+ mkstemp then fails (disk full/EMFILE/quota), the freshly-created
+ empty dest_dir must not be left orphaned -- it must be removed, and
+ the original mkstemp error must still be reported cleanly."""
+ import contextlib
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+
+ def boom(*args, **kwargs):
+ raise OSError("disk full")
+
+ if mode == "from_url":
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ args = ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"]
+ url_patch = patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ )
+ else:
+ src = self._write_workflow_dir(project_dir)
+ args = ["workflow", "add", str(src)] + (["--dev"] if mode == "dev" else [])
+ url_patch = contextlib.nullcontext()
+
+ with url_patch, pytest.MonkeyPatch.context() as mp:
+ mp.setattr("tempfile.mkstemp", boom)
+ result = runner.invoke(
+ app, args, input="y\n" if mode == "from_url" else None
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists(), "fresh-install dest_dir left orphaned after mkstemp failure"
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_reinstall_mkstemp_failure_preserves_preexisting_directory(
+ self, project_dir, monkeypatch
+ ):
+ """A pre-existing (reinstall) dest_dir must never be removed by the
+ mkstemp-failure cleanup -- only a directory _stage_workflow_file
+ itself just created."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+ installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ original_bytes = installed_yaml.read_bytes()
+ original_registry_entry = WorkflowRegistry(project_dir).get("align-wf")
+
+ (src / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
+ )
+
+ def boom(*args, **kwargs):
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr("tempfile.mkstemp", boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ assert installed_yaml.parent.is_dir()
+ assert installed_yaml.read_bytes() == original_bytes
+ assert WorkflowRegistry(project_dir).get("align-wf") == original_registry_entry
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ @pytest.mark.parametrize("mode", ["dev", "catalog"])
+ def test_stage_write_rejects_swapped_symlink(
+ self, project_dir, monkeypatch, mode
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ victim = project_dir / "victim.txt"
+ victim.write_text("untouched", encoding="utf-8")
+
+ real_stage = _commands._stage_workflow_file
+
+ def raced_stage(*args, **kwargs):
+ staged = real_stage(*args, **kwargs)
+ staged_path = getattr(staged, "path", staged)
+ staged_path.unlink()
+ staged_path.symlink_to(victim)
+ return staged
+
+ monkeypatch.setattr(_commands, "_stage_workflow_file", raced_stage)
+
+ if mode == "dev":
+ source = self._write_workflow_dir(project_dir)
+ args = ["workflow", "add", str(source), "--dev"]
+ else:
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ monkeypatch.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ )
+ args = ["workflow", "add", "align-wf"]
+
+ result = CliRunner().invoke(app, args)
+
+ assert result.exit_code != 0
+ assert victim.read_text(encoding="utf-8") == "untouched"
+
+ def test_local_install_writes_the_same_bytes_it_validates(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ source = self._write_workflow_dir(project_dir)
+ source_file = source / "workflow.yml"
+ validated_content = source_file.read_text(encoding="utf-8")
+ replacement_content = self.WORKFLOW_YAML.format(version="9.9.9")
+
+ real_stage = _commands._stage_workflow_file
+
+ def replace_source_after_validation(*args, **kwargs):
+ staged = real_stage(*args, **kwargs)
+ source_file.write_text(replacement_content, encoding="utf-8")
+ return staged
+
+ monkeypatch.setattr(
+ _commands,
+ "_stage_workflow_file",
+ replace_source_after_validation,
+ )
+
+ result = CliRunner().invoke(
+ app, ["workflow", "add", str(source), "--dev"]
+ )
+
+ assert result.exit_code == 0, result.output
+ installed_file = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "align-wf"
+ / "workflow.yml"
+ )
+ assert installed_file.read_text(encoding="utf-8") == validated_content
+ assert WorkflowRegistry(project_dir).get("align-wf")["version"] == "1.0.0"
+
+ def test_add_fresh_install_staged_discard_cleanup_failure_reports_warning(
+ self, project_dir, monkeypatch
+ ):
+ """A genuine fresh-directory rmdir failure must be reported while
+ the original copy failure remains the primary error."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._write_workflow_dir(project_dir)
+
+ def copy_boom(self, data):
+ raise OSError("disk full")
+
+ real_rmdir = Path.rmdir
+
+ def rmdir_boom(path):
+ if path.name == "align-wf":
+ raise OSError("cleanup denied")
+ return real_rmdir(path)
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(_commands._StagedWorkflowFile, "write_bytes", copy_boom)
+ mp.setattr(Path, "rmdir", rmdir_boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ # Original install error remains present and primary.
+ assert "disk full" in result.output
+ # Cleanup failure is now reported, not silently swallowed.
+ assert "cleanup denied" in result.output
+ assert "Warning" in result.output
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_fresh_install_registry_rollback_cleanup_failure_reports_warning(
+ self, project_dir, monkeypatch
+ ):
+ """A fresh-install rollback directory-removal failure must be
+ reported while the registry-update error remains primary."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._write_workflow_dir(project_dir)
+
+ def save_boom(self):
+ raise OSError("registry disk full")
+
+ real_rmdir = Path.rmdir
+
+ def rmdir_boom(path):
+ if path.name == "align-wf":
+ raise OSError("cleanup denied")
+ return real_rmdir(path)
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", save_boom)
+ mp.setattr(Path, "rmdir", rmdir_boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ # Original registry-update error remains present and primary.
+ assert "registry disk full" in result.output
+ # Cleanup failure is now reported, not silently swallowed.
+ assert "cleanup denied" in result.output
+ assert "Warning" in result.output
+
+ def test_add_dev_reinstall_copy_failure_leaves_prior_file_untouched(
+ self, project_dir, monkeypatch
+ ):
+ """A staged descriptor-copy failure cannot touch the prior installed
+ workflow or leave a staging file behind."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+ installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ original_bytes = installed_yaml.read_bytes()
+ original_registry_entry = WorkflowRegistry(project_dir).get("align-wf")
+
+ # Point --dev at a new version of the same workflow to trigger a
+ # reinstall (overwrite) rather than a fresh install.
+ (src / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
+ )
+
+ def boom(staged, data):
+ # Simulate a truncating partial write followed by an OSError on
+ # the reserved staging inode, mirroring disk exhaustion.
+ os.ftruncate(staged.fd, 0)
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(_commands._StagedWorkflowFile, "write_bytes", boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ assert installed_yaml.read_bytes() == original_bytes
+ assert WorkflowRegistry(project_dir).get("align-wf") == original_registry_entry
+ # No orphaned staging file left behind in the workflow directory.
+ leftovers = [p.name for p in installed_yaml.parent.iterdir() if p.name != "workflow.yml"]
+ assert leftovers == []
+
+ def test_add_dev_successful_reinstall_leaves_no_backup_file(
+ self, project_dir, monkeypatch
+ ):
+ """Once registry.add() succeeds, the unique rollback backup must be
+ discarded rather than left as a permanent orphan sibling."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+ workflow_dir = project_dir / ".specify" / "workflows" / "align-wf"
+
+ # Reinstall (overwrite) with a new version -- a successful reinstall,
+ # not a failure path.
+ (src / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
+ )
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code == 0, result.output
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "2.0.0"
+ assert (workflow_dir / "workflow.yml").read_text(encoding="utf-8") == (
+ self.WORKFLOW_YAML.format(version="2.0.0")
+ )
+ leftovers = [p.name for p in workflow_dir.iterdir() if p.name != "workflow.yml"]
+ assert leftovers == [], f"orphan sibling(s) left behind: {leftovers}"
+
+ def test_add_dev_successful_reinstall_backup_cleanup_failure_still_succeeds(
+ self, project_dir, monkeypatch
+ ):
+ """A failure to clean up the now-unneeded backup file after a
+ successful registry.add() must not turn the already-successful
+ install into a reported failure: it must be a warning (exit 0),
+ consistent with workflow_remove's post-commit cleanup semantics."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+
+ (src / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
+ )
+
+ real_unlink = Path.unlink
+
+ def unlink_boom(self_path, *args, **kwargs):
+ if self_path.name.endswith(".bak"):
+ raise OSError("permission denied")
+ return real_unlink(self_path, *args, **kwargs)
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(Path, "unlink", unlink_boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code == 0, result.output
+ assert "Warning" in result.output
+ assert "permissiondenied" in "".join(result.output.split())
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "2.0.0"
+
+ def test_add_dev_reinstall_restore_failure_reports_warning_and_original_error(
+ self, project_dir, monkeypatch
+ ):
+ """The prior file is now restored via an atomic rename (not a
+ content rewrite) when registry.add() fails on a reinstall. If that
+ restore rename itself also fails (e.g. a transient FS issue), it
+ must not silently claim success or crash with a raw traceback: it
+ must report a clear warning about the restore failure in addition
+ to the original clean registry error."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._install_dev(runner, app, project_dir)
+
+ (src / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
+ )
+
+ def save_boom(self):
+ raise OSError("disk full")
+
+ real_replace = os.replace
+ calls = {"n": 0}
+
+ def replace_boom(src_path, dst_path):
+ # The commit swap for a reinstall makes exactly two os.replace
+ # calls (backup-aside, then staged-into-dest); let both succeed
+ # and only fail the third call -- the post-registry-failure
+ # restore-back rename.
+ calls["n"] += 1
+ if calls["n"] <= 2:
+ return real_replace(src_path, dst_path)
+ raise OSError("permission denied")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", save_boom)
+ mp.setattr(os, "replace", replace_boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ output_compact = "".join(result.output.split())
+ assert "Warning" in result.output
+ assert "diskfull" in output_compact
+ assert "permissiondenied" in output_compact
+
+ def test_add_dev_fresh_install_into_preexisting_empty_dir_cleans_new_file(
+ self, project_dir, monkeypatch
+ ):
+ """When the destination directory already exists but has no
+ workflow.yml (e.g. an empty dir left over from elsewhere), a later
+ registry.add() failure must remove the newly copied file -- the
+ rollback previously did nothing in this case (existed_before=True
+ with no backup bytes), leaving the new file behind -- while leaving
+ the pre-existing directory itself intact."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ src = self._write_workflow_dir(project_dir)
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ dest_dir.mkdir(parents=True) # pre-existing, but empty: no workflow.yml
+
+ def boom(self, *args, **kwargs):
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "add", boom)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+
+ assert result.exit_code != 0
+ assert result.output.strip() != ""
+ assert dest_dir.is_dir()
+ assert not (dest_dir / "workflow.yml").exists()
+
+ def test_add_catalog_save_failure_leaves_no_orphan_directory(self, project_dir, monkeypatch):
+ """Same guarantee as the local-install paths, but for a fresh catalog
+ install: a registry.add() failure must clean up the freshly-downloaded
+ directory and fail with a clean escaped message."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+
+ def boom(self):
+ raise OSError("disk full")
+
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ )
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists()
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_catalog_fresh_install_mkstemp_failure_leaves_no_orphan_directory(
+ self, project_dir, monkeypatch
+ ):
+ """Same guarantee as the local-install fresh-install case, but for a
+ fresh catalog install: if _stage_workflow_file's mkdir succeeds but
+ its mkstemp then fails, the freshly-created empty directory must not
+ be left orphaned."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+
+ def boom(*args, **kwargs):
+ raise OSError("disk full")
+
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ )
+ mp.setattr("tempfile.mkstemp", boom)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists(), "fresh-install dest_dir left orphaned after mkstemp failure"
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_catalog_rejects_oversized_content_length(self, project_dir, monkeypatch):
+ """Catalog installs must share the same size cap as --from: a
+ response that declares an oversized Content-Length is rejected
+ before its body is read into memory, and no orphan directory or
+ registry mutation is left behind."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ small_body = b"id: align-wf\n" # actual body is small; header lies
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ small_body, url, headers={"Content-Length": "1000"}
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists()
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_catalog_rejects_oversized_streamed_body_without_content_length(
+ self, project_dir, monkeypatch
+ ):
+ """Catalog installs must also cap actual streamed bytes when
+ Content-Length is absent or understated, leaving no orphan
+ directory or registry mutation behind."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands as wf_commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ oversized_body = b"x" * 500 # no Content-Length header at all
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ oversized_body, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ assert not dest_dir.exists()
+ assert not WorkflowRegistry(project_dir).is_installed("align-wf")
+
+ def test_add_catalog_reinstall_save_failure_restores_prior_file(self, project_dir, monkeypatch):
+ """Re-adding an already-installed catalog workflow downloads the new
+ version over the existing install directory. If registry.add() then
+ fails to save, the prior working workflow.yml must be restored
+ byte-for-byte (not left overwritten with the new download, and not
+ deleted like a fresh install) and the registry must remain valid and
+ still point at the original version -- the update path's caller has
+ an outer backup/restore for this, but plain `workflow add` does not,
+ so _install_workflow_from_catalog must handle it itself."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ source_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ original_data = dest_file.read_bytes()
+
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+
+ def boom(self):
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ new_data, url
+ ),
+ )
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ # The prior working install must survive untouched, byte-for-byte.
+ assert dest_file.read_bytes() == original_data
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "1.0.0"
+
+ def test_add_catalog_successful_reinstall_leaves_no_backup_file(
+ self, project_dir, monkeypatch
+ ):
+ """Same orphan-backup gap as the local-install path: a successful
+ catalog reinstall must not leave its unique backup behind once
+ registry.add() durably succeeds."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ original_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ new_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code == 0, result.output
+ workflow_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "2.0.0"
+ assert (workflow_dir / "workflow.yml").read_bytes() == new_data
+ leftovers = [p.name for p in workflow_dir.iterdir() if p.name != "workflow.yml"]
+ assert leftovers == [], f"orphan sibling(s) left behind: {leftovers}"
+
+ @pytest.mark.skipif(os.name == "nt", reason="POSIX permission bits")
+ def test_add_catalog_fresh_install_uses_project_file_mode(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+
+ previous_umask = os.umask(0o022)
+ try:
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ )
+ result = CliRunner().invoke(
+ app, ["workflow", "add", "align-wf"]
+ )
+ finally:
+ os.umask(previous_umask)
+
+ assert result.exit_code == 0, result.output
+ workflow_file = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "align-wf"
+ / "workflow.yml"
+ )
+ assert stat.S_IMODE(workflow_file.stat().st_mode) == 0o644
+
+ def test_concurrent_catalog_reinstalls_keep_file_and_registry_aligned(
+ self, project_dir, monkeypatch
+ ):
+ import threading
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ workflows_dir = project_dir / ".specify" / "workflows"
+ workflow_file = workflows_dir / "align-wf" / "workflow.yml"
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ WorkflowRegistry(project_dir).add(
+ "align-wf",
+ {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "source": "catalog",
+ },
+ )
+
+ versions = {"install-a": "2.0.0", "install-b": "3.0.0"}
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": versions[threading.current_thread().name],
+ "url": (
+ "https://example.com/"
+ f"{versions[threading.current_thread().name]}.yml"
+ ),
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ monkeypatch.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(
+ self.WORKFLOW_YAML.format(
+ version=url.rsplit("/", 1)[-1].removesuffix(".yml")
+ ).encode(),
+ url,
+ ),
+ )
+
+ a_committed = threading.Event()
+ b_committed = threading.Event()
+ a_saving = threading.Event()
+ b_saved = threading.Event()
+ real_commit = _commands._commit_workflow_file
+ real_save = WorkflowRegistry.save
+
+ def coordinated_commit(*args, **kwargs):
+ backup = real_commit(*args, **kwargs)
+ if threading.current_thread().name == "install-a":
+ a_committed.set()
+ b_committed.wait(0.5)
+ else:
+ b_committed.set()
+ return backup
+
+ def coordinated_save(registry):
+ if threading.current_thread().name == "install-a":
+ a_saving.set()
+ b_saved.wait(0.5)
+ return real_save(registry)
+ assert a_saving.wait(2)
+ real_save(registry)
+ b_saved.set()
+
+ monkeypatch.setattr(
+ _commands, "_commit_workflow_file", coordinated_commit
+ )
+ monkeypatch.setattr(WorkflowRegistry, "save", coordinated_save)
+
+ errors = []
+
+ def install():
+ try:
+ _commands._install_workflow_from_catalog(
+ project_dir,
+ workflows_dir,
+ "align-wf",
+ )
+ except BaseException as exc:
+ errors.append(exc)
+
+ first = threading.Thread(target=install, name="install-a")
+ second = threading.Thread(target=install, name="install-b")
+ first.start()
+ assert a_committed.wait(2)
+ second.start()
+ first.join(5)
+ second.join(5)
+
+ assert not first.is_alive()
+ assert not second.is_alive()
+ assert errors == []
+ file_version = WorkflowDefinition.from_yaml(workflow_file).version
+ registry_version = WorkflowRegistry(project_dir).get("align-wf")[
+ "version"
+ ]
+ assert file_version == registry_version
+
+ def test_precommit_discard_preserves_concurrent_install(self, project_dir):
+ from specify_cli.workflows import _commands
+
+ workflow_dir = (
+ project_dir / ".specify" / "workflows" / "concurrent-wf"
+ )
+ workflow_dir.mkdir(parents=True)
+ staged_file = workflow_dir / ".workflow.yml.staged.tmp"
+ staged_file.write_text("staged", encoding="utf-8")
+ committed_file = workflow_dir / "workflow.yml"
+ committed_file.write_text("committed", encoding="utf-8")
+
+ _commands._discard_staged_workflow_file(
+ staged_file, workflow_dir, existed_before=False
+ )
+
+ assert committed_file.read_text(encoding="utf-8") == "committed"
+ assert not staged_file.exists()
+
+ def test_fresh_install_rollback_preserves_concurrent_staged_file(
+ self, project_dir
+ ):
+ """A second installer stages before taking the transaction lock, so
+ the first installer's rollback must not recursively remove siblings."""
+ from specify_cli.workflows import _commands
+
+ workflow_dir = (
+ project_dir / ".specify" / "workflows" / "concurrent-wf"
+ )
+ workflow_dir.mkdir(parents=True)
+ committed_file = workflow_dir / "workflow.yml"
+ committed_file.write_text("failed install", encoding="utf-8")
+ concurrent_stage = workflow_dir / ".workflow.yml.concurrent.tmp"
+ concurrent_stage.write_text("next install", encoding="utf-8")
+
+ _commands._rollback_committed_workflow_file(
+ committed_file,
+ workflow_dir,
+ existed_before=False,
+ backup_file=None,
+ )
+
+ assert not committed_file.exists()
+ assert concurrent_stage.read_text(encoding="utf-8") == "next install"
+
+ def test_add_dev_registry_reopen_exit_discards_staged_file(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+
+ monkeypatch.chdir(project_dir)
+ source_dir = self._write_workflow_dir(project_dir)
+ real_open_registry = _commands._open_workflow_registry
+ calls = 0
+
+ def fail_transaction_reopen(root):
+ nonlocal calls
+ calls += 1
+ if calls == 2:
+ raise typer.Exit(1)
+ return real_open_registry(root)
+
+ monkeypatch.setattr(
+ _commands, "_open_workflow_registry", fail_transaction_reopen
+ )
+ result = CliRunner().invoke(
+ app, ["workflow", "add", str(source_dir), "--dev"]
+ )
+
+ assert result.exit_code != 0
+ assert not (
+ project_dir / ".specify" / "workflows" / "align-wf"
+ ).exists()
+
+ def test_add_catalog_registry_reopen_exit_discards_staged_file(
+ self, project_dir, monkeypatch
+ ):
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ workflows_dir = project_dir / ".specify" / "workflows"
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ monkeypatch.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ )
+ monkeypatch.setattr(
+ _commands,
+ "_open_workflow_registry",
+ lambda _root: (_ for _ in ()).throw(typer.Exit(1)),
+ )
+
+ with pytest.raises(typer.Exit):
+ _commands._install_workflow_from_catalog(
+ project_dir,
+ workflows_dir,
+ "align-wf",
+ )
+
+ assert not (workflows_dir / "align-wf").exists()
+
+ def test_add_catalog_reinstall_restore_failure_reports_warning_and_original_error(
+ self, project_dir, monkeypatch
+ ):
+ """Same restore-rename boundary as the local-install path: the
+ prior file is restored via an atomic rename (not a content rewrite)
+ when registry.add() fails on a reinstall. If that restore rename
+ itself also fails, it must report a clear warning in addition to
+ the original clean registry error, never crash or silently claim
+ success."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ original_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+
+ def save_boom(self):
+ raise OSError("disk full")
+
+ real_replace = os.replace
+ calls = {"n": 0}
+
+ def replace_boom(src_path, dst_path):
+ # The commit swap for a reinstall makes exactly two os.replace
+ # calls (backup-aside, then staged-into-dest); let both succeed
+ # and only fail the third call -- the post-registry-failure
+ # restore-back rename.
+ calls["n"] += 1
+ if calls["n"] <= 2:
+ return real_replace(src_path, dst_path)
+ raise OSError("permission denied")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ new_data, url
+ ),
+ )
+ mp.setattr(WorkflowRegistry, "save", save_boom)
+ mp.setattr(os, "replace", replace_boom)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ output_compact = "".join(result.output.split())
+ assert "Warning" in result.output
+ assert "diskfull" in output_compact
+ assert "permissiondenied" in output_compact
+
+ def test_add_catalog_fresh_install_into_preexisting_empty_dir_cleans_new_file(
+ self, project_dir, monkeypatch
+ ):
+ """Same rollback orphan gap as the local-install path, but for a
+ fresh catalog install: a pre-existing empty destination directory
+ (no workflow.yml) sets existed_before=True with no backup bytes, so
+ the rollback previously did nothing on a later failure -- leaving
+ the freshly downloaded workflow.yml behind. It must be removed,
+ leaving the pre-existing directory itself intact."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ dest_dir.mkdir(parents=True) # pre-existing, but empty: no workflow.yml
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+
+ def boom(self):
+ raise OSError("disk full")
+
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ )
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.output.strip() != ""
+ assert dest_dir.is_dir()
+ assert not (dest_dir / "workflow.yml").exists()
+
+ @pytest.mark.parametrize(
+ "mode", ["redirect_rejected", "download_exception", "invalid_yaml", "id_mismatch"]
+ )
+ def test_add_catalog_reinstall_early_failure_restores_prior_file(
+ self, project_dir, monkeypatch, mode
+ ):
+ """Every _install_workflow_from_catalog failure branch that runs after
+ the mkdir/download step -- not just the registry.add() OSError case
+ -- must route through the same existed-before/backup-aware cleanup:
+ on a reinstall, a redirect rejection, a download exception, invalid
+ YAML, or a workflow-id mismatch must restore the prior working
+ workflow.yml rather than deleting the whole directory. One shared
+ root cause (the cleanup helper), so parametrized over trigger point."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ source_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ original_data = dest_file.read_bytes()
+
+ if mode == "redirect_rejected":
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ return self._FakeResponse(b"irrelevant", "http://evil.example.com/workflow.yml")
+ elif mode == "download_exception":
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ raise OSError("network down")
+ elif mode == "invalid_yaml":
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ return self._FakeResponse(b": : not valid yaml: [", url)
+ else: # id_mismatch
+ mismatched_yaml = self.WORKFLOW_YAML.format(version="2.0.0").replace(
+ 'id: "align-wf"', 'id: "different-workflow"'
+ )
+
+ def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
+ return self._FakeResponse(mismatched_yaml.encode(), url)
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr("specify_cli.authentication.http.open_url", fake_open_url)
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ assert dest_file.read_bytes() == original_data
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "1.0.0"
+
+ def test_download_redirect_validator_rejects_http_before_follow(self):
+ import urllib.error
+
+ from specify_cli.workflows._commands import _reject_insecure_download_redirect
+
+ with pytest.raises(urllib.error.URLError):
+ _reject_insecure_download_redirect(
+ "https://example.com/wf.yml", "http://evil.example.com/wf.yml"
+ )
+ with pytest.raises(urllib.error.URLError):
+ _reject_insecure_download_redirect(
+ "https://example.com/wf.yml", "http://localhost:8000/wf.yml"
+ )
+ with pytest.raises(urllib.error.URLError):
+ _reject_insecure_download_redirect(
+ "https://example.com/wf.yml", "https://127.0.0.2/wf.yml"
+ )
+ # Allowed: HTTPS anywhere, or loopback HTTP that stays on loopback HTTP.
+ _reject_insecure_download_redirect(
+ "https://example.com/wf.yml", "https://cdn.example.com/wf.yml"
+ )
+ _reject_insecure_download_redirect(
+ "http://localhost:7000/wf.yml", "http://localhost:8000/wf.yml"
+ )
+ _reject_insecure_download_redirect(
+ "http://127.0.0.1/source.yml", "http://127.0.0.1/wf.yml"
+ )
+ _reject_insecure_download_redirect(
+ "http://127.0.0.2/source.yml", "http://127.255.255.254/wf.yml"
+ )
+
+ def test_add_from_url_passes_redirect_validator(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ seen: dict[str, object] = {}
+
+ def fake_open(url, timeout=None, extra_headers=None, redirect_validator=None):
+ seen["validator"] = redirect_validator
+ return self._FakeResponse(data, url)
+
+ runner = CliRunner()
+ with patch("specify_cli.authentication.http.open_url", side_effect=fake_open):
+ result = runner.invoke(
+ app,
+ ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
+ input="y\n",
+ )
+ assert result.exit_code == 0, result.output
+ from specify_cli.workflows._commands import _reject_insecure_download_redirect
+
+ assert seen["validator"] is _reject_insecure_download_redirect
+
+ def test_add_non_string_catalog_url_fails_cleanly(self, project_dir, monkeypatch):
+ """A truthy non-string catalog URL must hit the clean error path, not AttributeError."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": 123,
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "malformed install URL" in result.output
+
+ def test_commit_failure_reports_unrestored_backup_location(
+ self, tmp_path, monkeypatch
+ ):
+ from specify_cli.workflows import _commands
+
+ dest_dir = tmp_path / "align-wf"
+ dest_dir.mkdir()
+ dest_file = dest_dir / "workflow.yml"
+ staged_file = dest_dir / ".workflow.yml.staged"
+ dest_file.write_text("original", encoding="utf-8")
+ staged_file.write_text("replacement", encoding="utf-8")
+
+ real_replace = os.replace
+ calls = 0
+ backup_file = None
+
+ def fail_commit_and_restore(src, dst):
+ nonlocal backup_file, calls
+ calls += 1
+ if calls == 1:
+ backup_file = Path(dst)
+ return real_replace(src, dst)
+ if calls == 2:
+ raise OSError("commit denied")
+ raise OSError("restore denied")
+
+ monkeypatch.setattr(os, "replace", fail_commit_and_restore)
+ with pytest.raises(OSError) as exc_info:
+ _commands._commit_workflow_file(
+ staged_file, dest_file, existed_before=True
+ )
+
+ message = str(exc_info.value)
+ assert "commit denied" in message
+ assert "restore denied" in message
+ assert backup_file is not None
+ assert str(backup_file) in message
+ assert not dest_file.exists()
+ assert backup_file.read_text(encoding="utf-8") == "original"
+
+ def test_commit_keyboard_interrupt_restores_prior_file(
+ self, tmp_path, monkeypatch
+ ):
+ from specify_cli.workflows import _commands
+
+ dest_dir = tmp_path / "align-wf"
+ dest_dir.mkdir()
+ dest_file = dest_dir / "workflow.yml"
+ staged_file = dest_dir / ".workflow.yml.staged"
+ dest_file.write_text("original", encoding="utf-8")
+ staged_file.write_text("replacement", encoding="utf-8")
+
+ real_replace = os.replace
+ calls = 0
+
+ def interrupt_commit(src, dst):
+ nonlocal calls
+ calls += 1
+ if calls == 2:
+ raise KeyboardInterrupt
+ return real_replace(src, dst)
+
+ monkeypatch.setattr(os, "replace", interrupt_commit)
+ with pytest.raises(KeyboardInterrupt):
+ _commands._commit_workflow_file(
+ staged_file, dest_file, existed_before=True
+ )
+
+ assert dest_file.read_text(encoding="utf-8") == "original"
+ assert staged_file.read_text(encoding="utf-8") == "replacement"
+ assert list(dest_dir.glob("*.bak")) == []
+
+ def test_commit_interrupt_after_first_rename_restores_prior_file(
+ self, tmp_path, monkeypatch
+ ):
+ from specify_cli.workflows import _commands
+
+ dest_dir = tmp_path / "align-wf"
+ dest_dir.mkdir()
+ dest_file = dest_dir / "workflow.yml"
+ staged_file = dest_dir / ".workflow.yml.staged"
+ dest_file.write_text("original", encoding="utf-8")
+ staged_file.write_text("replacement", encoding="utf-8")
+
+ real_replace = os.replace
+ calls = 0
+
+ def interrupt_after_replace(src, dst):
+ nonlocal calls
+ calls += 1
+ result = real_replace(src, dst)
+ if calls == 1:
+ raise KeyboardInterrupt
+ return result
+
+ monkeypatch.setattr(os, "replace", interrupt_after_replace)
+ with pytest.raises(KeyboardInterrupt):
+ _commands._commit_workflow_file(
+ staged_file, dest_file, existed_before=True
+ )
+
+ assert dest_file.read_text(encoding="utf-8") == "original"
+ assert staged_file.read_text(encoding="utf-8") == "replacement"
+ assert list(dest_dir.glob("*.bak")) == []
+
+ def test_commit_uses_unique_backup_without_overwriting_existing_sibling(
+ self, tmp_path
+ ):
+ from specify_cli.workflows import _commands
+
+ dest_dir = tmp_path / "align-wf"
+ dest_dir.mkdir()
+ dest_file = dest_dir / "workflow.yml"
+ staged_file = dest_dir / ".workflow.yml.staged"
+ fixed_backup = dest_dir / "workflow.yml.bak"
+ dest_file.write_text("original", encoding="utf-8")
+ staged_file.write_text("replacement", encoding="utf-8")
+ fixed_backup.write_text("diagnostic copy", encoding="utf-8")
+
+ backup_file = _commands._commit_workflow_file(
+ staged_file, dest_file, existed_before=True
+ )
+
+ assert backup_file is not None
+ assert backup_file != fixed_backup
+ assert backup_file.read_text(encoding="utf-8") == "original"
+ assert fixed_backup.read_text(encoding="utf-8") == "diagnostic copy"
+ assert dest_file.read_text(encoding="utf-8") == "replacement"
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_workflow_add_does_not_copy_overlays(self, project_dir, monkeypatch, tmp_path):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ source_dir = tmp_path / "source-wf"
+ source_dir.mkdir()
+ (source_dir / "workflow.yml").write_text(
+ yaml.safe_dump(
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ overlays_dir = source_dir / "overlays"
+ overlays_dir.mkdir()
+ (overlays_dir / "ov1.yml").write_text(
+ yaml.safe_dump(
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ result = runner.invoke(app, ["workflow", "add", str(source_dir)])
+ assert result.exit_code == 0, result.output
+ # Overlays in the source directory should NOT be copied — workflow add
+ # only installs the workflow.yml, not sibling overlays.
+ installed_overlay = (
+ project_dir / ".specify" / "workflows" / "wf" / "overlays" / "ov1.yml"
+ )
+ assert not installed_overlay.exists()
diff --git a/tests/specify_cli/workflows/test_command_disable.py b/tests/specify_cli/workflows/test_command_disable.py
new file mode 100644
index 000000000..b95930d7c
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_disable.py
@@ -0,0 +1,305 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ class _FakeResponse:
+ def __init__(self, data, url="https://example.com/workflow.yml", headers=None):
+ self._data = data
+ self._url = url
+ self._pos = 0
+ self._headers = headers or {}
+
+ def read(self, amt=None):
+ if amt is None:
+ chunk = self._data[self._pos :]
+ self._pos = len(self._data)
+ return chunk
+ chunk = self._data[self._pos : self._pos + amt]
+ self._pos += len(chunk)
+ return chunk
+
+ def getheader(self, name, default=None):
+ return self._headers.get(name, default)
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ @pytest.mark.parametrize(
+ ("command_name", "initial_enabled", "expected_enabled"),
+ [
+ ("enable", False, True),
+ ("disable", True, False),
+ ],
+ )
+ def test_toggle_serializes_with_concurrent_catalog_update(
+ self,
+ project_dir,
+ monkeypatch,
+ command_name,
+ initial_enabled,
+ expected_enabled,
+ ):
+ import threading
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ workflows_dir = project_dir / ".specify" / "workflows"
+ workflow_file = workflows_dir / "align-wf" / "workflow.yml"
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ WorkflowRegistry(project_dir).add(
+ "align-wf",
+ {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "source": "catalog",
+ "enabled": initial_enabled,
+ },
+ )
+ monkeypatch.setattr(
+ _commands, "_require_specify_project", lambda: project_dir
+ )
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ monkeypatch.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(new_data, url),
+ )
+
+ toggle_ready = threading.Event()
+ update_done = threading.Event()
+ real_add = WorkflowRegistry.add
+
+ def coordinated_add(registry, workflow_id, metadata):
+ if threading.current_thread().name == "toggle":
+ toggle_ready.set()
+ update_done.wait(0.5)
+ return real_add(registry, workflow_id, metadata)
+
+ monkeypatch.setattr(WorkflowRegistry, "add", coordinated_add)
+ errors = []
+
+ def toggle():
+ try:
+ getattr(_commands, f"workflow_{command_name}")("align-wf")
+ except BaseException as exc:
+ errors.append(exc)
+
+ def update():
+ try:
+ _commands._install_workflow_from_catalog(
+ project_dir,
+ workflows_dir,
+ "align-wf",
+ )
+ except BaseException as exc:
+ errors.append(exc)
+ finally:
+ update_done.set()
+
+ toggle_thread = threading.Thread(target=toggle, name="toggle")
+ update_thread = threading.Thread(target=update, name="update")
+ toggle_thread.start()
+ assert toggle_ready.wait(2)
+ update_thread.start()
+ toggle_thread.join(5)
+ update_thread.join(5)
+
+ assert not toggle_thread.is_alive()
+ assert not update_thread.is_alive()
+ assert errors == []
+ assert WorkflowDefinition.from_yaml(workflow_file).version == "2.0.0"
+ metadata = WorkflowRegistry(project_dir).get("align-wf")
+ assert metadata["version"] == "2.0.0"
+ assert metadata.get("enabled", True) is expected_enabled
+
+ def test_disable_blocks_run_enable_restores(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
+
+ result = runner.invoke(app, ["workflow", "run", "align-wf"])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ result = runner.invoke(app, ["workflow", "enable", "align-wf"])
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is True
+
+ result = runner.invoke(app, ["workflow", "run", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ def test_disable_blocks_case_variant_installed_path(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ case_variant = (
+ project_dir
+ / ".SPECIFY"
+ / "WORKFLOWS"
+ / "ALIGN-WF"
+ / "workflow.yml"
+ )
+ if not case_variant.is_file():
+ pytest.skip("filesystem is case-sensitive")
+
+ result = runner.invoke(
+ app, ["workflow", "run", str(case_variant)]
+ )
+
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ def test_disable_blocks_run_via_path_equivalent_id(self, project_dir, monkeypatch):
+ """Path-equivalent and newline IDs must not dodge the registry lookup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ for spelling in ("align-wf/", "align-wf/.", "align-wf\n"):
+ result = runner.invoke(app, ["workflow", "run", spelling])
+ assert result.exit_code != 0, spelling
+ assert "Invalid workflow ID" in result.output, spelling
+
+ # Direct path to the installed workflow's own YAML must also refuse.
+ installed_yaml = ".specify/workflows/align-wf/workflow.yml"
+ assert (project_dir / installed_yaml).is_file()
+ result = runner.invoke(app, ["workflow", "run", installed_yaml])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ # Same guard must hold when invoked from outside the project.
+ outside = project_dir.parent / "outside-cwd"
+ outside.mkdir(exist_ok=True)
+ monkeypatch.chdir(outside)
+ result = runner.invoke(
+ app, ["workflow", "run", str(project_dir / installed_yaml)]
+ )
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_disable_blocks_run_when_installed_yaml_is_symlinked(
+ self, project_dir, monkeypatch
+ ):
+ """A disabled workflow's own workflow.yml being replaced with a symlink
+ must not bypass the disabled check. Resolving the path before mapping
+ it back to its registry owner would follow the symlink out of
+ .specify/workflows, fail to find an owner, and let engine.load_workflow
+ run the original symlink target anyway -- ownership must be
+ determined from the normalized *lexical* path (not resolve()), and a
+ symlinked path component in the installed tree must be refused."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ external_target = project_dir / "external-workflow.yml"
+ external_target.write_text(
+ self.WORKFLOW_YAML.format(version="9.9.9"), encoding="utf-8"
+ )
+ installed_yaml.unlink()
+ installed_yaml.symlink_to(external_target)
+
+ result = runner.invoke(app, ["workflow", "run", str(installed_yaml)])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "disabled" in result.output or "symlink" in result.output.lower()
+
+ def test_disable_shows_marker_in_list(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+ runner.invoke(app, ["workflow", "disable", "align-wf"])
+ result = runner.invoke(app, ["workflow", "list"])
+ assert result.exit_code == 0, result.output
+ assert "[disabled]" in result.output
diff --git a/tests/specify_cli/workflows/test_command_enable.py b/tests/specify_cli/workflows/test_command_enable.py
new file mode 100644
index 000000000..8c615af83
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_enable.py
@@ -0,0 +1,145 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ def test_enable_failed_save_leaves_workflow_disabled(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ def boom(self):
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(app, ["workflow", "enable", "align-wf"])
+ assert result.exit_code != 0
+
+ assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
+ result = runner.invoke(app, ["workflow", "enable", "align-wf"])
+ assert result.exit_code == 0, result.output
+ assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is True
+
+ @pytest.mark.parametrize("command", ["enable", "disable"])
+ def test_enable_disable_save_failure_gives_clean_output(
+ self, project_dir, monkeypatch, command
+ ):
+ """A save() failure in enable/disable must produce a clean escaped CLI
+ error, not surface the raw OSError as an unhandled exception. Shared
+ root behavior: both call registry.add() with a fresh mapping and must
+ catch its deliberate OSError the same way."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+ # disable starts from the enabled default; enable needs a prior disable.
+ starting_enabled = command == "disable"
+ if command == "enable":
+ pre = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert pre.exit_code == 0, pre.output
+
+ def boom(self):
+ raise OSError("disk full")
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = runner.invoke(app, ["workflow", command, "align-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ assert (
+ WorkflowRegistry(project_dir).get("align-wf").get("enabled", True)
+ is starting_enabled
+ )
+
+ def test_enable_disable_corrupted_registry_entry_errors(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(
+ json.dumps({"schema_version": "1.0", "workflows": {"broken": "not-a-dict"}}),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ for cmd in ("enable", "disable"):
+ result = runner.invoke(app, ["workflow", cmd, "broken"])
+ assert result.exit_code != 0
+ assert "corrupted" in result.output
+
+ def test_enable_disable_not_installed_errors(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ for cmd in ("enable", "disable"):
+ result = runner.invoke(app, ["workflow", cmd, "ghost"])
+ assert result.exit_code != 0
+ assert "not installed" in result.output
+
+ def test_enable_disable_idempotent_warnings(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "enable", "align-wf"])
+ assert result.exit_code == 0
+ assert "already enabled" in result.output
+
+ runner.invoke(app, ["workflow", "disable", "align-wf"])
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0
+ assert "already disabled" in result.output
diff --git a/tests/specify_cli/workflows/test_command_info.py b/tests/specify_cli/workflows/test_command_info.py
new file mode 100644
index 000000000..2956c0b95
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_info.py
@@ -0,0 +1,143 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowInfoStepGraph:
+ """`workflow info` must render each step as `→ <id> [<type>]` with LITERAL
+ brackets. Rich parses an unescaped `[<type>]` as a style tag and silently
+ swallows it, so the step type would vanish from the output."""
+
+ def test_step_type_rendered_in_literal_brackets(self, temp_dir, monkeypatch):
+ import types
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowEngine
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+
+ fake = types.SimpleNamespace(
+ name="My WF", id="my-wf", version="1.0.0", author="", description="",
+ default_integration=None, inputs={},
+ steps=[{"id": "step-one", "type": "gate"}],
+ )
+ monkeypatch.setattr(WorkflowEngine, "load_workflow", lambda self, wid: fake)
+ monkeypatch.chdir(temp_dir)
+
+ result = CliRunner().invoke(app, ["workflow", "info", "my-wf"])
+
+ assert result.exit_code == 0, result.output
+ assert "step-one" in result.output
+ # The step type must survive as a literal bracketed token, not be eaten
+ # by Rich as an unknown style tag.
+ assert "[gate]" in result.output
+
+ def test_definition_metadata_fields_escaped(self, temp_dir, monkeypatch):
+ """Every metadata field printed from the workflow definition (name,
+ description, author, integration, input name/type) is untrusted
+ workflow.yml content. An unescaped `[...]` in any of them would be
+ parsed as a Rich style tag and silently swallowed, so bracketed text
+ must survive literally in the output."""
+ import types
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowEngine
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+
+ fake = types.SimpleNamespace(
+ name="My [WF]",
+ id="my-wf",
+ version="1.0.0 [beta]",
+ author="Jane [Doe]",
+ description="Does [stuff] nicely",
+ default_integration="claude [code]",
+ inputs={"in [put]": {"type": "str [ing]", "required": True}},
+ steps=[],
+ )
+ monkeypatch.setattr(WorkflowEngine, "load_workflow", lambda self, wid: fake)
+ monkeypatch.chdir(temp_dir)
+
+ result = CliRunner().invoke(app, ["workflow", "info", "my-wf"])
+
+ assert result.exit_code == 0, result.output
+ # Each bracketed token must render literally rather than be consumed as
+ # an unknown Rich style tag.
+ assert "My [WF]" in result.output
+ assert "1.0.0 [beta]" in result.output
+ assert "Jane [Doe]" in result.output
+ assert "Does [stuff] nicely" in result.output
+ assert "claude [code]" in result.output
+ assert "in [put]" in result.output
+ assert "str [ing]" in result.output
+
+ def test_catalog_metadata_fields_escaped(self, temp_dir, monkeypatch):
+ """When the workflow is only found in the catalog (not on disk), its
+ catalog-derived fields (name, description, tags) are untrusted too and
+ must be escaped so bracketed content renders literally."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowEngine
+ from specify_cli.workflows import catalog as catalog_mod
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+
+ def _not_on_disk(self, wid):
+ raise FileNotFoundError(wid)
+
+ monkeypatch.setattr(WorkflowEngine, "load_workflow", _not_on_disk)
+ monkeypatch.setattr(
+ catalog_mod.WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "name": "Cat [WF]",
+ "version": "2.0.0 [rc]",
+ "description": "From [catalog]",
+ "tags": ["a [b]", "c [d]"],
+ },
+ )
+ monkeypatch.chdir(temp_dir)
+
+ result = CliRunner().invoke(app, ["workflow", "info", "cat-wf"])
+
+ assert result.exit_code == 0, result.output
+ assert "Cat [WF]" in result.output
+ assert "2.0.0 [rc]" in result.output
+ assert "From [catalog]" in result.output
+ assert "a [b]" in result.output
+ assert "c [d]" in result.output
+
+ def test_not_found_id_escaped(self, temp_dir, monkeypatch):
+ """When the workflow is neither on disk nor in the catalog, the
+ not-found error echoes the requested ID. That ID is user input, so a
+ bracketed value must render literally instead of being parsed (and
+ swallowed) as a Rich style tag."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowEngine
+ from specify_cli.workflows import catalog as catalog_mod
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+
+ def _not_on_disk(self, wid):
+ raise FileNotFoundError(wid)
+
+ monkeypatch.setattr(WorkflowEngine, "load_workflow", _not_on_disk)
+ monkeypatch.setattr(
+ catalog_mod.WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: None,
+ )
+ monkeypatch.chdir(temp_dir)
+
+ result = CliRunner().invoke(app, ["workflow", "info", "ghost [wf]"])
+
+ assert result.exit_code == 1, result.output
+ assert "not found" in result.output
+ # The bracketed ID must survive literally, not be eaten as markup.
+ assert "ghost [wf]" in result.output
diff --git a/tests/specify_cli/workflows/test_command_list.py b/tests/specify_cli/workflows/test_command_list.py
new file mode 100644
index 000000000..18e42cf5c
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_list.py
@@ -0,0 +1,150 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+
+
+class TestWorkflowAddSymlinkGuard:
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_list_refuses_symlinked_runs_dir(self, temp_dir, monkeypatch):
+ """workflow commands using the project shim must refuse symlinked run storage."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ outside = temp_dir.parent / "outside-runs-target"
+ outside.mkdir(parents=True, exist_ok=True)
+ (temp_dir / ".specify" / "workflows" / "runs").symlink_to(
+ outside, target_is_directory=True
+ )
+
+ monkeypatch.chdir(temp_dir)
+ result = CliRunner().invoke(app, ["workflow", "list"])
+
+ assert result.exit_code != 0
+ assert "symlinked .specify/workflows/runs" in result.output
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ def test_list_skips_corrupted_registry_entry(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ "broken": "not-a-dict",
+ "ok": {"name": "OK Workflow", "version": "1.0.0"},
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "list"])
+ assert result.exit_code == 0, result.output
+ assert "corrupted" in result.output
+ assert "OK Workflow" in result.output
+
+ def test_list_unreadable_registry_fails_closed_with_clean_error(
+ self, project_dir, monkeypatch
+ ):
+ """An unreadable registry file must produce a clean CLI error, not a
+ raw traceback and not a silent "nothing installed" list -- the latter
+ is exactly the fail-open state a caller could otherwise mistake for
+ "safe to (re)install", overwriting real files. Covers the read/query
+ boundary fix required at every WorkflowRegistry call site."""
+ import builtins
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ registry_path = WorkflowRegistry(project_dir).registry_path.resolve()
+ real_open = builtins.open
+
+ def _raising_open(file, mode="r", *args, **kwargs):
+ if Path(file).resolve() == registry_path and "r" in mode:
+ raise OSError("simulated read failure")
+ return real_open(file, mode, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "open", _raising_open)
+ result = runner.invoke(app, ["workflow", "list"])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Error" in result.output
+
+ def test_list_escapes_rich_markup_in_registry_fields(self, project_dir, monkeypatch):
+ """User-editable name/description/id fields must not be parsed as Rich markup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ "ok": {
+ "name": "Bracket [Test]",
+ "version": "1.0.0",
+ "description": "desc [with] brackets",
+ },
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "list"])
+ assert result.exit_code == 0, result.output
+ assert "Bracket [Test]" in result.output
+ assert "desc [with] brackets" in result.output
diff --git a/tests/specify_cli/workflows/test_command_remove.py b/tests/specify_cli/workflows/test_command_remove.py
new file mode 100644
index 000000000..21b0347e3
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_remove.py
@@ -0,0 +1,371 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+
+class TestWorkflowRemoveGuard:
+ def test_remove_rejects_traversal_registry_key(self, project_dir, monkeypatch):
+ """A corrupted registry key must not let remove delete outside workflows/."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("../outside", {"name": "Bad"})
+ outside = project_dir / ".specify" / "outside"
+ outside.mkdir()
+ sentinel = outside / "keep.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+
+ monkeypatch.chdir(project_dir)
+ result = CliRunner().invoke(app, ["workflow", "remove", "../outside"])
+
+ assert result.exit_code != 0
+ assert "Invalid workflow ID" in result.output
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+
+ @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])
+ def test_remove_rejects_reserved_storage_ids(
+ self, project_dir, monkeypatch, workflow_id
+ ):
+ """Reserved workflow storage directories must never be removable workflows."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add(workflow_id, {"name": "Bad"})
+ reserved_dir = project_dir / ".specify" / "workflows" / workflow_id
+ reserved_dir.mkdir(exist_ok=True)
+ sentinel = reserved_dir / "keep.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+
+ monkeypatch.chdir(project_dir)
+ result = CliRunner().invoke(app, ["workflow", "remove", workflow_id])
+
+ assert result.exit_code != 0
+ assert "Invalid workflow ID" in result.output
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_remove_refuses_symlinked_workflow_dir(self, project_dir, monkeypatch):
+ """A symlinked workflow directory must not let remove delete its target."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("test-wf", {"name": "Test"})
+ outside = project_dir / "outside-workflow-remove-target"
+ outside.mkdir(exist_ok=True)
+ sentinel = outside / "keep.txt"
+ sentinel.write_text("keep", encoding="utf-8")
+ (project_dir / ".specify" / "workflows" / "test-wf").symlink_to(
+ outside, target_is_directory=True
+ )
+
+ monkeypatch.chdir(project_dir)
+ result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+
+ assert result.exit_code != 0
+ assert "symlinked .specify/workflows/test-wf" in result.output
+ assert sentinel.read_text(encoding="utf-8") == "keep"
+ assert WorkflowRegistry(project_dir).is_installed("test-wf")
+
+ def test_remove_refuses_non_directory_workflow_path(self, project_dir, monkeypatch):
+ """A file at the workflow path must fail cleanly instead of crashing."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("test-wf", {"name": "Test"})
+ workflow_path = project_dir / ".specify" / "workflows" / "test-wf"
+ workflow_path.write_text("not a directory", encoding="utf-8")
+
+ monkeypatch.chdir(project_dir)
+ result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+
+ assert result.exit_code != 0
+ assert "exists but is not a directory" in result.output
+ assert workflow_path.read_text(encoding="utf-8") == "not a directory"
+ assert WorkflowRegistry(project_dir).is_installed("test-wf")
+
+ @pytest.mark.parametrize("error_type", [OSError, TypeError, ValueError])
+ def test_remove_registry_save_failure_preserves_files_and_registry(
+ self, project_dir, monkeypatch, error_type
+ ):
+ """If persisting the registry removal fails, the workflow's files must
+ not have already been deleted: the CLI must not delete files before the
+ registry successfully records the removal, and it must fail cleanly."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
+ workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
+ workflow_dir.mkdir(parents=True, exist_ok=True)
+ (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
+
+ def boom(self):
+ raise error_type("save failed")
+
+ monkeypatch.chdir(project_dir)
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", boom)
+ result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert result.output.strip() != ""
+ # Files must survive a registry-save failure.
+ assert (workflow_dir / "workflow.yml").read_text(encoding="utf-8") == "keep-me"
+ # The on-disk registry must still claim the workflow installed.
+ assert WorkflowRegistry(project_dir).is_installed("test-wf")
+ # The directory must be restored to its exact original location, with
+ # no leftover staging directory from the stage/restore-on-failure
+ # sequence.
+ entries = [
+ p.name
+ for p in (project_dir / ".specify" / "workflows").iterdir()
+ if p.name != "workflow-registry.json"
+ ]
+ assert entries == ["test-wf"]
+
+ def test_remove_staged_cleanup_failure_reports_warning_not_error(
+ self, project_dir, monkeypatch
+ ):
+ """The directory is staged (atomically renamed out of
+ .specify/workflows/<id>) *before* the registry write, and the actual
+ deletion of the staged directory only happens *after* the registry
+ has already durably recorded the removal. If that final deletion
+ fails, the registry write already succeeded and must stand -- an
+ "Error: Failed to remove..." message at that point would contradict
+ the registry, which is exactly the incoherent state this staging
+ order exists to prevent. It must be reported as a cleanup warning,
+ and the command must still succeed."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
+ workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
+ workflow_dir.mkdir(parents=True, exist_ok=True)
+ (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
+
+ def boom(*args, **kwargs):
+ raise OSError("permission denied")
+
+ monkeypatch.chdir(project_dir)
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr("shutil.rmtree", boom)
+ result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+
+ assert result.exit_code == 0
+ assert "Warning" in result.output
+ # The registry write already committed -- it must stand.
+ assert not WorkflowRegistry(project_dir).is_installed("test-wf")
+ # The original install path is gone (staged away before the registry
+ # write ever ran); only a leftover staged directory remains, never
+ # at the original path the registry/CLI would treat as installed.
+ assert not workflow_dir.exists()
+ leftovers = [
+ p
+ for p in (project_dir / ".specify" / "workflows").iterdir()
+ if p.name != "workflow-registry.json"
+ ]
+ assert len(leftovers) == 1
+ assert (leftovers[0] / "workflow.yml").read_text(encoding="utf-8") == "keep-me"
+
+ def test_remove_stage_restore_failure_escapes_rich_markup(
+ self, temp_dir, monkeypatch
+ ):
+ """When the registry write fails (already rolled back in-memory by
+ WorkflowRegistry.remove()) and the attempt to rename the staged
+ directory back to its original location also fails, both the
+ restore exception and the registry-update exception interpolated
+ into these warning/error messages must be escaped like every other
+ error path here."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ project_dir = temp_dir / "weird[project]"
+ project_dir.mkdir()
+ (project_dir / ".specify").mkdir()
+ (project_dir / ".specify" / "workflows").mkdir()
+
+ registry = WorkflowRegistry(project_dir)
+ registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
+ workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
+ workflow_dir.mkdir(parents=True, exist_ok=True)
+ (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
+
+ def save_boom(self):
+ raise OSError("[reg] disk full")
+
+ real_rename = os.rename
+ rename_calls = {"n": 0}
+
+ def rename_boom(src, dst):
+ rename_calls["n"] += 1
+ if rename_calls["n"] == 1:
+ # Allow the initial stage-out rename to succeed so the
+ # restore-back rename (the second call) is what fails.
+ return real_rename(src, dst)
+ raise OSError("[stage] permission denied")
+
+ monkeypatch.chdir(project_dir)
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(WorkflowRegistry, "save", save_boom)
+ mp.setattr(os, "rename", rename_boom)
+ result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ output_compact = "".join(result.output.split())
+ assert "[stage]permissiondenied" in output_compact
+ assert "[reg]diskfull" in output_compact
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ class _FakeResponse:
+ def __init__(self, data, url="https://example.com/workflow.yml", headers=None):
+ self._data = data
+ self._url = url
+ self._pos = 0
+ self._headers = headers or {}
+
+ def read(self, amt=None):
+ if amt is None:
+ chunk = self._data[self._pos :]
+ self._pos = len(self._data)
+ return chunk
+ chunk = self._data[self._pos : self._pos + amt]
+ self._pos += len(chunk)
+ return chunk
+
+ def getheader(self, name, default=None):
+ return self._headers.get(name, default)
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def test_remove_serializes_with_concurrent_catalog_install(
+ self, project_dir, monkeypatch
+ ):
+ import threading
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ workflows_dir = project_dir / ".specify" / "workflows"
+ workflow_file = workflows_dir / "align-wf" / "workflow.yml"
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ WorkflowRegistry(project_dir).add(
+ "align-wf",
+ {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "source": "catalog",
+ },
+ )
+ monkeypatch.setattr(
+ _commands, "_require_specify_project", lambda: project_dir
+ )
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ monkeypatch.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(new_data, url),
+ )
+
+ removal_ready = threading.Event()
+ install_done = threading.Event()
+ real_remove = WorkflowRegistry.remove
+
+ def coordinated_remove(registry, workflow_id):
+ if threading.current_thread().name == "remove":
+ removal_ready.set()
+ install_done.wait(0.5)
+ return real_remove(registry, workflow_id)
+
+ monkeypatch.setattr(WorkflowRegistry, "remove", coordinated_remove)
+ errors = []
+
+ def remove():
+ try:
+ _commands.workflow_remove("align-wf")
+ except BaseException as exc:
+ errors.append(exc)
+
+ def install():
+ try:
+ _commands._install_workflow_from_catalog(
+ project_dir,
+ workflows_dir,
+ "align-wf",
+ )
+ except BaseException as exc:
+ errors.append(exc)
+ finally:
+ install_done.set()
+
+ remove_thread = threading.Thread(target=remove, name="remove")
+ install_thread = threading.Thread(target=install, name="install")
+ remove_thread.start()
+ assert removal_ready.wait(2)
+ install_thread.start()
+ remove_thread.join(5)
+ install_thread.join(5)
+
+ assert not remove_thread.is_alive()
+ assert not install_thread.is_alive()
+ assert errors == []
+ assert WorkflowDefinition.from_yaml(workflow_file).version == "2.0.0"
+ metadata = WorkflowRegistry(project_dir).get("align-wf")
+ assert metadata["version"] == "2.0.0"
diff --git a/tests/specify_cli/workflows/test_command_resolve.py b/tests/specify_cli/workflows/test_command_resolve.py
new file mode 100644
index 000000000..0e4cdf37f
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_resolve.py
@@ -0,0 +1,197 @@
+"""Command-focused workflow overlay tests."""
+
+from __future__ import annotations
+
+
+import pytest
+from typer.testing import CliRunner
+
+from specify_cli import app
+from tests.specify_cli.workflows.helpers import (
+ write_overlay as _write_overlay,
+ write_workflow as _write_workflow,
+)
+
+runner = CliRunner()
+
+
+class TestOverlayCli:
+ """CLI-level tests for ``specify workflow overlay *``."""
+
+ def test_workflow_resolve(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "resolve", "wf"])
+ assert result.exit_code == 0, result.output
+ assert "base" in result.output
+ assert "project:ov1" in result.output
+ assert "new" in result.output
+ assert "priority=n/a" in result.output
+
+ from specify_cli.workflows.overlay.operations import workflow_resolve
+
+ payload = workflow_resolve(project_dir, "wf")
+ assert payload is not None
+ assert payload["layers"][-1]["tier"] == "base"
+ assert payload["layers"][-1]["priority"] is None
+
+ def test_workflow_resolve_prints_tier_labels(self, project_dir, monkeypatch):
+ """Layer tiers render literally; an unescaped ``[base]`` is eaten as markup."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "new", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "resolve", "wf"])
+ assert result.exit_code == 0, result.output
+ assert "[base]" in result.output
+ assert "[project-overlay]" in result.output
+
+ @pytest.mark.parametrize(
+ "step_id",
+ [
+ # Balanced tag: silently swallowed, so the step vanishes from output.
+ "new[stuff]",
+ # Unbalanced closer: raises MarkupError -> traceback and exit 1.
+ "new[/red]",
+ ],
+ )
+ def test_workflow_resolve_escapes_rich_markup_in_step_id(
+ self, project_dir, monkeypatch, step_id
+ ):
+ """Step IDs are unvalidated for brackets, so they must be escaped."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "ov1",
+ {
+ "id": "ov1",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": step_id, "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "resolve", "wf"])
+ assert result.exit_code == 0, result.output
+ assert step_id in result.output
+
+ def test_workflow_resolve_equal_priority_layers_sort_by_source(self, project_dir, monkeypatch):
+ """Equal-priority overlays are listed alphabetically by source."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ # "zzz" sorts last alphabetically, so the composer applies it last and wins.
+ # Resolver layer output follows the common priority/source sort order.
+ _write_overlay(
+ project_dir,
+ "wf",
+ "aaa",
+ {
+ "id": "aaa",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "aaa-step", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+ _write_overlay(
+ project_dir,
+ "wf",
+ "zzz",
+ {
+ "id": "zzz",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [
+ {
+ "operation": "insert_after",
+ "anchor": "a",
+ "step": {"id": "zzz-step", "type": "command", "command": "echo"},
+ }
+ ],
+ },
+ )
+
+ result = runner.invoke(app, ["workflow", "resolve", "wf"])
+ assert result.exit_code == 0, result.output
+ zzz_pos = result.output.index("project:zzz")
+ aaa_pos = result.output.index("project:aaa")
+ assert aaa_pos < zzz_pos
diff --git a/tests/specify_cli/workflows/test_command_resume.py b/tests/specify_cli/workflows/test_command_resume.py
new file mode 100644
index 000000000..c4f0c050c
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_resume.py
@@ -0,0 +1,652 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import pytest
+
+
+
+class TestWorkflowJsonOutput:
+ """Test the --json machine-readable output for run/resume/status."""
+
+ _WF = """
+schema_version: "1.0"
+workflow:
+ id: "json-wf"
+ name: "JSON WF"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+ - id: after
+ type: shell
+ run: "echo done"
+"""
+
+ def _write_wf(self, project_dir, text, name):
+ path = project_dir / f"{name}.yml"
+ path.write_text(text, encoding="utf-8")
+ return path
+
+ def _invoke(self, project_dir, args):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ return runner.invoke(app, args, catch_exceptions=False)
+
+ def test_resume_json(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF, "gated3")
+ rid = json.loads(
+ self._invoke(project_dir, ["workflow", "run", str(wf), "--json"]).stdout
+ )["run_id"]
+ # Non-interactive resume re-runs the gate, which pauses again.
+ resumed = json.loads(
+ self._invoke(project_dir, ["workflow", "resume", rid, "--json"]).stdout
+ )
+ assert resumed["run_id"] == rid
+ assert resumed["status"] == "paused"
+
+
+
+class TestResumeWithInputs:
+ """Test that `workflow resume` can accept updated workflow inputs."""
+
+ _WF_NUM = """
+schema_version: "1.0"
+workflow:
+ id: "resume-num-wf"
+ name: "Resume Num WF"
+ version: "1.0.0"
+inputs:
+ count:
+ type: number
+ default: 1
+steps:
+ - id: gate
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+"""
+
+ def _engine(self, project_dir):
+ from specify_cli.workflows.engine import WorkflowEngine
+ return WorkflowEngine(project_dir)
+
+ def test_cli_resume_input_invalid_format_errors(self, project_dir):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ definition = WorkflowDefinition.from_string(self._WF_NUM)
+ state = self._engine(project_dir).execute(definition)
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ result = runner.invoke(
+ app, ["workflow", "resume", state.run_id, "--input", "bogus"]
+ )
+ assert result.exit_code == 1
+ assert "Invalid input format" in result.stdout
+
+
+
+class TestWorkflowStepStartProgressLine:
+ """The `run`/`resume` step-progress line must render the step id literally.
+
+ The line is built as ` ▸ [<id>] <label> …`, so Rich parsed the bracketed id
+ as a style tag: it silently swallowed the id (the only identifying content
+ on the line), applied it as formatting when the id happened to be a real
+ style like `bold`, and raised MarkupError — failing the whole run — when the
+ id formed a closing tag such as `/`. `validate_workflow` places no charset
+ restriction on step ids, so all of these are accepted workflows.
+ """
+
+ def test_resume_progress_line_shows_step_id(self, tmp_path, monkeypatch):
+ """`workflow resume` installs its own copy of the same callback, so it
+ needs independent coverage — a one-line fix would miss the twin."""
+ import json as _json
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ path = tmp_path / "wf.yml"
+ path.write_text(
+ 'schema_version: "1.0"\n'
+ "workflow:\n"
+ ' id: "probe-resume"\n'
+ ' name: "Probe"\n'
+ ' version: "1.0.0"\n'
+ "steps:\n"
+ " - id: boom\n"
+ " type: shell\n"
+ ' run: "exit 1"\n',
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ first = runner.invoke(app, ["workflow", "run", str(path), "--json"])
+ run_id = _json.loads(first.stdout).get("run_id")
+ assert run_id
+
+ resumed = runner.invoke(app, ["workflow", "resume", run_id])
+ assert "[boom]" in resumed.stdout
+
+
+
+class TestWorkflowRunExitCodes:
+ """CLI-level tests for the run/resume process exit codes."""
+
+ _WF_FAIL = """
+schema_version: "1.0"
+workflow:
+ id: "exit-fail"
+ name: "Exit Fail"
+ version: "1.0.0"
+steps:
+ - id: boom
+ type: shell
+ run: "exit 1"
+"""
+
+ def _write(self, tmp_path, content):
+ path = tmp_path / "wf.yml"
+ path.write_text(content, encoding="utf-8")
+ return path
+
+ def test_resume_failed_run_exits_nonzero(self, tmp_path, monkeypatch):
+ # End-to-end coverage for the `workflow resume` exit-code mapping:
+ # resuming a run whose outcome is still `failed` must exit non-zero,
+ # mirroring `workflow run`. Resume re-executes the failed step, which
+ # fails again, so the resumed outcome stays `failed`.
+ import json as _json
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ (tmp_path / ".specify").mkdir() # `workflow resume` requires a project
+ runner = CliRunner()
+ run = runner.invoke(
+ app,
+ ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL)), "--json"],
+ )
+ assert run.exit_code == 1, run.stdout
+ run_id = _json.loads(run.stdout)["run_id"]
+
+ resumed = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert resumed.exit_code == 1, resumed.stdout
+ payload = _json.loads(resumed.stdout)
+ assert payload["status"] == "failed"
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ _GATED_WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "gated-wf"
+ name: "Gated Workflow"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+"""
+
+ def _install_and_run_gated(self, runner, app, project_dir):
+ """Install a gate-step workflow and run it to a paused state.
+
+ Returns the run_id. The gate step pauses without any interactive
+ input, giving a resumable run tied to an installed workflow ID.
+ """
+ src = project_dir / "gated-src"
+ src.mkdir(exist_ok=True)
+ (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+
+ result = runner.invoke(app, ["workflow", "run", "gated-wf", "--json"])
+ assert result.exit_code == 0, result.output
+ payload = json.loads(result.stdout)
+ assert payload["status"] == "paused"
+ return payload["run_id"]
+
+ def test_resume_blocks_when_installed_workflow_disabled(
+ self, project_dir, monkeypatch
+ ):
+ """A run started from an installed workflow must not resume once
+ that workflow is disabled. engine.resume() replays the persisted
+ run directly from disk with no registry awareness at all, so the
+ installed workflow's origin (id + owning registry root) is
+ persisted at run start and re-checked against the registry's
+ *current* state before resuming, mirroring `workflow run`'s
+ disabled guard."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
+ assert result.exit_code == 0, result.output
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ # Re-enabling must unblock the exact same run.
+ result = runner.invoke(app, ["workflow", "enable", "gated-wf"])
+ assert result.exit_code == 0, result.output
+ result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert result.exit_code == 0, result.output
+ resumed = json.loads(result.stdout)
+ assert resumed["run_id"] == run_id
+
+ def test_resume_rejects_corrupted_registry_entry(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ registry = WorkflowRegistry(project_dir)
+ registry.data["workflows"]["gated-wf"] = "corrupted"
+ registry.save()
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert "corrupted" in result.output
+
+ def test_resume_preload_io_error_is_reported_cleanly(
+ self, project_dir, monkeypatch
+ ):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.engine import RunState
+
+ monkeypatch.chdir(project_dir)
+ with patch.object(
+ RunState, "load", side_effect=OSError("permission [denied]")
+ ):
+ result = CliRunner().invoke(
+ app, ["workflow", "resume", "unreadable-run"]
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Resume failed" in result.output
+ assert "permission [denied]" in result.output
+
+ @pytest.mark.parametrize("malformation", ["non-object", "missing-run-id"])
+ def test_resume_preload_rejects_malformed_state_cleanly(
+ self, project_dir, monkeypatch, malformation
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+
+ if malformation == "non-object":
+ state_path.write_text("[]", encoding="utf-8")
+ else:
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data.pop("run_id")
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Invalid run state" in result.output
+
+ def test_resume_rejects_out_of_range_current_step_index(
+ self, project_dir, monkeypatch
+ ):
+ """An out-of-range positive index must fail cleanly, not silently
+ complete the run with no steps executed.
+
+ ``resume()`` slices ``definition.steps[state.current_step_index:]``;
+ for any index >= len(steps) that slice is an empty list, so the run
+ would otherwise finish with status "completed" having executed
+ nothing.
+ """
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data["current_step_index"] = 5
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Invalid run state" in result.output
+ assert "out of range" in result.output
+
+ reloaded = json.loads(state_path.read_text(encoding="utf-8"))
+ assert reloaded["status"] == "paused"
+
+ def test_resume_legacy_run_respects_current_disabled_state(
+ self, project_dir, monkeypatch
+ ):
+ """Legacy runs infer same-project registry ownership before resume."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data.pop("installed_workflow_id", None)
+ data.pop("installed_registry_root", None)
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
+ assert result.exit_code == 0, result.output
+
+ result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ def test_resume_migrates_legacy_installed_origin_metadata(
+ self, project_dir, monkeypatch
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data.pop("installed_workflow_id", None)
+ data.pop("installed_registry_root", None)
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert result.exit_code == 0, result.output
+
+ migrated = json.loads(state_path.read_text(encoding="utf-8"))
+ assert migrated["installed_workflow_id"] == "gated-wf"
+ assert migrated["installed_registry_root"] is None
+
+ def test_resume_blocks_after_project_moved_following_disable(
+ self, temp_dir, monkeypatch
+ ):
+ """Renaming/moving the entire project after starting a run must not
+ let a subsequent disable-then-resume bypass the guard. Persisting
+ the run's *creation-time absolute* project path would make resume
+ open a now-nonexistent old root (WorkflowRegistry falls back to an
+ empty default there), missing the disabled entry that actually
+ lives in the *current* (moved) project's registry. The common,
+ same-project case must instead re-derive the owning root from the
+ project's current location on every resume."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ project_v1 = temp_dir / "project-v1"
+ (project_v1 / ".specify" / "workflows").mkdir(parents=True)
+ monkeypatch.chdir(project_v1)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_v1)
+
+ project_v2 = temp_dir / "project-v2"
+ monkeypatch.chdir(temp_dir)
+ shutil.move(str(project_v1), str(project_v2))
+ monkeypatch.chdir(project_v2)
+
+ result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
+ assert result.exit_code == 0, result.output
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ def test_resume_after_project_moved_still_works_when_enabled(
+ self, temp_dir, monkeypatch
+ ):
+ """The inverse of the move regression: an enabled workflow's run
+ must still resume normally after the project is moved -- the
+ current-project fallback must not itself block legitimate
+ resumes."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ project_v1 = temp_dir / "project-v1-ok"
+ (project_v1 / ".specify" / "workflows").mkdir(parents=True)
+ monkeypatch.chdir(project_v1)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_v1)
+
+ project_v2 = temp_dir / "project-v2-ok"
+ monkeypatch.chdir(temp_dir)
+ shutil.move(str(project_v1), str(project_v2))
+ monkeypatch.chdir(project_v2)
+
+ result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert result.exit_code == 0, result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_resume_respects_cross_project_registry_root(
+ self, temp_dir, monkeypatch
+ ):
+ """A run started via a direct workflow.yml path belonging to a
+ different project than the cwd used for `workflow run`/`workflow
+ resume` must still gate resuming on *that* owning project's
+ registry, not the cwd project's (which has no entry for this ID
+ at all). This is the genuine cross-project case that must remain
+ unaffected by only special-casing the common same-project one."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ owner_project = temp_dir / "owner-project"
+ (owner_project / ".specify" / "workflows").mkdir(parents=True)
+ monkeypatch.chdir(owner_project)
+ runner = CliRunner()
+ src = owner_project / "gated-src"
+ src.mkdir()
+ (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+
+ unrelated_cwd = temp_dir / "unrelated-cwd"
+ unrelated_cwd.mkdir()
+ monkeypatch.chdir(unrelated_cwd)
+
+ owner_alias = temp_dir / "owner-project-alias"
+ owner_alias.symlink_to(owner_project, target_is_directory=True)
+ target = owner_alias / ".specify" / "workflows" / "gated-wf" / "workflow.yml"
+ result = runner.invoke(app, ["workflow", "run", str(target), "--json"])
+ assert result.exit_code == 0, result.output
+ run_id = json.loads(result.stdout)["run_id"]
+ state_path = (
+ unrelated_cwd
+ / ".specify"
+ / "workflows"
+ / "runs"
+ / run_id
+ / "state.json"
+ )
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ assert state["installed_registry_root"] == str(owner_project.resolve())
+
+ monkeypatch.chdir(owner_project)
+ result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
+ assert result.exit_code == 0, result.output
+
+ # Resume must run from unrelated_cwd (where this run's own
+ # state.json actually lives) yet still be blocked by the owner
+ # project's disabled entry.
+ monkeypatch.chdir(unrelated_cwd)
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ def test_resume_rejects_missing_cross_project_owner_root(
+ self, temp_dir, monkeypatch
+ ):
+ """A vanished explicit cross-project owner cannot be safely
+ rediscovered, so resume must fail closed instead of consulting the
+ unrelated project that stores the run state."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ owner_project = temp_dir / "owner-project-2"
+ (owner_project / ".specify" / "workflows").mkdir(parents=True)
+ monkeypatch.chdir(owner_project)
+ runner = CliRunner()
+ src = owner_project / "gated-src"
+ src.mkdir()
+ (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+
+ unrelated_cwd = temp_dir / "unrelated-cwd-2"
+ unrelated_cwd.mkdir()
+ monkeypatch.chdir(unrelated_cwd)
+
+ target = owner_project / ".specify" / "workflows" / "gated-wf" / "workflow.yml"
+ result = runner.invoke(app, ["workflow", "run", str(target), "--json"])
+ assert result.exit_code == 0, result.output
+ run_id = json.loads(result.stdout)["run_id"]
+
+ # owner_project vanishes entirely -- its persisted absolute root
+ # is now dangling.
+ shutil.rmtree(owner_project)
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert "owner" in result.output.lower()
+ assert "unavailable" in result.output.lower()
+
+ @pytest.mark.parametrize(
+ "field, bad_value",
+ [
+ ("installed_workflow_id", 123),
+ ("installed_workflow_id", ["gated-wf"]),
+ ("installed_workflow_id", {"id": "gated-wf"}),
+ ("installed_workflow_id", True),
+ ("installed_workflow_id", ""),
+ ("installed_workflow_id", "gated-wf\n"),
+ ("installed_registry_root", 123),
+ ("installed_registry_root", ["."]),
+ ("installed_registry_root", {"root": "."}),
+ ("installed_registry_root", False),
+ ("installed_registry_root", ""),
+ ("installed_registry_root", "relative-owner"),
+ ],
+ )
+ def test_resume_rejects_malformed_run_state_origin_fields(
+ self, project_dir, monkeypatch, field, bad_value
+ ):
+ """RunState.load() rejects malformed or unsafe origin metadata
+ before registry/path lookups and reports a clean CLI error."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data[field] = bad_value
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "resume", run_id])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Error" in result.output
+
+ @pytest.mark.parametrize("command", ["resume", "status"])
+ def test_state_load_errors_escape_rich_markup(
+ self, project_dir, monkeypatch, command
+ ):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ malicious_status = "[bold red]forged[/bold red]"
+ data["status"] = malicious_status
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", command, run_id])
+
+ assert result.exit_code != 0
+ assert malicious_status in result.output
+
+ @pytest.mark.parametrize(
+ "installed_workflow_id, installed_registry_root",
+ [
+ (None, None),
+ ("gated-wf", None),
+ ],
+ )
+ def test_resume_accepts_valid_run_state_origin_fields(
+ self, project_dir, monkeypatch, installed_workflow_id, installed_registry_root
+ ):
+ """Valid installed-origin values continue to load and resume."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data["installed_workflow_id"] = installed_workflow_id
+ data["installed_registry_root"] = installed_registry_root
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
+ assert result.exit_code == 0, result.output
diff --git a/tests/specify_cli/workflows/test_command_resume_state.py b/tests/specify_cli/workflows/test_command_resume_state.py
new file mode 100644
index 000000000..9d354c27a
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_resume_state.py
@@ -0,0 +1,40 @@
+"""Tests for resume-private persisted state ownership."""
+
+import os
+
+import pytest
+
+
+class TestWorkflowCliAlignment:
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_resume_rejects_symlinked_cross_project_owner_root(
+ self, project_dir, tmp_path
+ ):
+ from specify_cli.workflows._command_resume_state import (
+ _resolve_run_owner_root,
+ )
+
+ real_owner = tmp_path / "real-owner"
+ real_owner.mkdir()
+ owner_link = tmp_path / "owner-link"
+ owner_link.symlink_to(real_owner, target_is_directory=True)
+
+ with pytest.raises(ValueError, match="unavailable"):
+ _resolve_run_owner_root(str(owner_link), project_dir)
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_resume_rejects_cross_project_owner_with_symlinked_ancestor(
+ self, project_dir, tmp_path
+ ):
+ from specify_cli.workflows._command_resume_state import (
+ _resolve_run_owner_root,
+ )
+
+ real_parent = tmp_path / "real-parent"
+ owner = real_parent / "owner"
+ owner.mkdir(parents=True)
+ parent_link = tmp_path / "parent-link"
+ parent_link.symlink_to(real_parent, target_is_directory=True)
+
+ with pytest.raises(ValueError, match="unavailable"):
+ _resolve_run_owner_root(str(parent_link / "owner"), project_dir)
diff --git a/tests/specify_cli/workflows/test_command_run.py b/tests/specify_cli/workflows/test_command_run.py
new file mode 100644
index 000000000..432ed6a48
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_run.py
@@ -0,0 +1,1394 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import pytest
+import yaml
+
+from tests.specify_cli.workflows.helpers import force_gate_stdin as _force_gate_stdin
+
+
+class TestWorkflowRunGateOutcomeJson:
+ """CLI-level tests: the --json payload surfaces gate pauses."""
+
+ _WF_GATE = """
+schema_version: "1.0"
+workflow:
+ id: "gate-json"
+ name: "Gate JSON"
+ version: "1.0.0"
+steps:
+ - id: review
+ type: gate
+ message: "Approve the thing?"
+ options: ["approve", "reject"]
+"""
+
+ _WF_PLAIN = """
+schema_version: "1.0"
+workflow:
+ id: "plain-json"
+ name: "Plain JSON"
+ version: "1.0.0"
+steps:
+ - id: fine
+ type: shell
+ run: "exit 0"
+"""
+
+ def _run_json(self, tmp_path, monkeypatch, content, *, expected_exit=0):
+ import json as _json
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ path = tmp_path / "wf.yml"
+ path.write_text(content, encoding="utf-8")
+ monkeypatch.chdir(tmp_path)
+ result = CliRunner().invoke(app, ["workflow", "run", str(path), "--json"])
+ # Assert the expected exit code before parsing so a real failure
+ # surfaces the actual output instead of an opaque JSON decode error.
+ # A terminal run still emits its JSON payload, then exits non-zero on
+ # ``failed``/``aborted`` (see ``_run_outcome_exit_code``), so callers
+ # pass the expected code. Use ``result.output`` for the message:
+ # under ``--json`` step output is redirected off stdout, so the useful
+ # diagnostics live there.
+ assert result.exit_code == expected_exit, result.output
+ return _json.loads(result.stdout)
+
+ def test_gate_pause_carries_gate_block(self, tmp_path, monkeypatch):
+ # CliRunner stdin is not a TTY, so the gate pauses for resume.
+ payload = self._run_json(tmp_path, monkeypatch, self._WF_GATE)
+ assert payload["status"] == "paused"
+ assert payload["gate"] == {
+ "step_id": "review",
+ "message": "Approve the thing?",
+ "options": ["approve", "reject"],
+ "choice": None,
+ }
+
+ def test_completed_run_has_no_gate_block(self, tmp_path, monkeypatch):
+ payload = self._run_json(tmp_path, monkeypatch, self._WF_PLAIN)
+ assert payload["status"] == "completed"
+ assert "gate" not in payload
+
+ def test_gate_abort_carries_gate_block(self, tmp_path, monkeypatch):
+ # An interactive gate the operator rejects ends the run as `aborted`
+ # (on_reject defaults to abort), not `paused`. The JSON surface must
+ # still carry the gate block with the recorded choice so an
+ # orchestrator can see *why* the run stopped. A gate abort emits the
+ # payload and then exits non-zero (aborted → exit 1), so the helper
+ # is told to expect exit code 1.
+ from specify_cli.workflows.step.gate import GateStep
+
+ _force_gate_stdin(monkeypatch, tty=True)
+ monkeypatch.setattr(
+ GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
+ )
+ payload = self._run_json(
+ tmp_path, monkeypatch, self._WF_GATE, expected_exit=1
+ )
+ assert payload["status"] == "aborted"
+ assert payload["gate"] == {
+ "step_id": "review",
+ "message": "Approve the thing?",
+ "options": ["approve", "reject"],
+ "choice": "reject",
+ }
+
+ def test_gate_block_emitted_only_when_run_rests_at_gate(self):
+ # A run rests *on* a gate only while `paused` (awaiting a decision) or
+ # `aborted` (gate rejected with on_reject: abort). current_step_id is
+ # not cleared afterwards, so a `completed`/`failed` run whose last
+ # executed step was a gate must NOT surface a stale gate block.
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ gate_step = {
+ "type": "gate",
+ "output": {
+ "message": "m",
+ "options": ["approve", "reject"],
+ "choice": "reject",
+ },
+ }
+
+ def _state(status):
+ return SimpleNamespace(
+ status=SimpleNamespace(value=status),
+ current_step_id="review",
+ step_results={"review": gate_step},
+ )
+
+ assert _gate_outcome(_state("completed")) is None
+ assert _gate_outcome(_state("failed")) is None
+ assert _gate_outcome(_state("paused")) is not None
+ assert _gate_outcome(_state("aborted")) is not None
+
+ def test_gate_block_message_coerced_to_string(self):
+ # message may be a non-string YAML literal (e.g. a number); the JSON
+ # surface normalises it so the emitted schema stays stable.
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {"message": 12.5, "options": ["ok"], "choice": None},
+ }
+ },
+ )
+ assert _gate_outcome(state)["message"] == "12.5"
+
+ def test_gate_block_options_coerced_to_strings(self):
+ # options may be non-string / non-list literals in an unvalidated
+ # workflow; the JSON surface always normalises them to list[str] | None
+ # so the emitted schema is stable regardless of the input shape.
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ def _options_payload(options):
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {
+ "message": "m",
+ "options": options,
+ "choice": None,
+ },
+ }
+ },
+ )
+ return _gate_outcome(state)["options"]
+
+ assert _options_payload([1, 2.5]) == ["1", "2.5"] # list
+ assert _options_payload(("approve", "reject")) == ["approve", "reject"] # tuple
+ assert _options_payload("approve") == ["approve"] # bare scalar, not iterated
+ assert _options_payload(7) == ["7"] # numeric scalar
+ assert _options_payload(None) is None # absent stays absent
+
+ def test_gate_block_choice_coerced_to_string(self):
+ # An unvalidated gate can record a non-string choice; the JSON
+ # surface normalises it to str (and keeps None = no decision yet),
+ # consistent with the message/options normalization.
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ def _choice_payload(choice):
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ "type": "gate",
+ "output": {"message": "m", "options": ["ok"], "choice": choice},
+ }
+ },
+ )
+ return _gate_outcome(state)["choice"]
+
+ assert _choice_payload(None) is None # no decision yet
+ assert _choice_payload("reject") == "reject" # normal string passes through
+ assert _choice_payload(2) == "2" # non-string coerced
+
+ def test_gate_block_detected_without_type_field(self):
+ # A run paused by an older version has no persisted step `type`. The
+ # gate is still detected by its unique output signature (`on_reject`),
+ # so resume surfaces the gate block instead of silently dropping it.
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="review",
+ step_results={
+ "review": {
+ # no "type" key — pre-dates the field being persisted
+ "output": {
+ "message": "Approve?",
+ "options": ["approve", "reject"],
+ "on_reject": "abort",
+ "choice": None,
+ },
+ }
+ },
+ )
+ gate = _gate_outcome(state)
+ assert gate is not None
+ assert gate["step_id"] == "review"
+ assert gate["options"] == ["approve", "reject"]
+
+ def test_non_gate_step_without_type_is_not_a_gate(self):
+ # A typeless record lacking the gate signature must NOT be mistaken for
+ # a gate (the fallback keys off `on_reject`, which only GateStep writes).
+ from types import SimpleNamespace
+ from specify_cli.workflows._commands import _gate_outcome
+
+ state = SimpleNamespace(
+ status=SimpleNamespace(value="paused"),
+ current_step_id="run-tests",
+ step_results={
+ "run-tests": {"output": {"exit_code": 0, "stdout": "ok"}},
+ },
+ )
+ assert _gate_outcome(state) is None
+
+
+
+class TestWorkflowJsonOutput:
+ """Test the --json machine-readable output for run/resume/status."""
+
+ _WF = """
+schema_version: "1.0"
+workflow:
+ id: "json-wf"
+ name: "JSON WF"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+ - id: after
+ type: shell
+ run: "echo done"
+"""
+
+ _WF_DONE = """
+schema_version: "1.0"
+workflow:
+ id: "json-done"
+ name: "JSON Done"
+ version: "1.0.0"
+steps:
+ - id: only
+ type: shell
+ run: "echo done"
+"""
+
+ _WF_FAIL = """
+schema_version: "1.0"
+workflow:
+ id: "json-fail"
+ name: "JSON Fail"
+ version: "1.0.0"
+steps:
+ - id: boom
+ type: shell
+ run: "exit 3"
+"""
+
+ def _write_wf(self, project_dir, text, name):
+ path = project_dir / f"{name}.yml"
+ path.write_text(text, encoding="utf-8")
+ return path
+
+ def _invoke(self, project_dir, args):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ return runner.invoke(app, args, catch_exceptions=False)
+
+ def test_run_json_completed(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF_DONE, "done")
+ result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
+ assert result.exit_code == 0
+ payload = json.loads(result.stdout)
+ assert payload["workflow_id"] == "json-done"
+ assert payload["status"] == "completed"
+ assert "run_id" in payload
+
+ def test_run_json_paused(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF, "gated")
+ result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
+ assert result.exit_code == 0
+ payload = json.loads(result.stdout)
+ assert payload["status"] == "paused"
+ assert payload["current_step_id"] == "ask"
+ assert payload["current_step_index"] == 0
+
+ def test_run_json_failed_includes_error(self, project_dir):
+ # A run that ends in `failed` (a step failing, not an exception) must
+ # carry the persisted step error in the JSON payload so external
+ # callers get a reason, not a bare {"status": "failed"}.
+ wf = self._write_wf(project_dir, self._WF_FAIL, "boom")
+ result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
+ assert result.exit_code != 0
+ payload = json.loads(result.stdout)
+ assert payload["status"] == "failed"
+ assert payload.get("error")
+
+ def test_run_json_completed_omits_error(self, project_dir):
+ # Successful runs must not carry an `error` key at all.
+ wf = self._write_wf(project_dir, self._WF_DONE, "noerr")
+ payload = json.loads(
+ self._invoke(
+ project_dir, ["workflow", "run", str(wf), "--json"]
+ ).stdout
+ )
+ assert payload["status"] == "completed"
+ assert "error" not in payload
+
+ def test_run_json_output_has_no_markup_or_ansi(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF_DONE, "clean")
+ out = self._invoke(
+ project_dir, ["workflow", "run", str(wf), "--json"]
+ ).stdout
+ # Machine output must be exactly the JSON object: no Rich markup
+ # tags and no ANSI escape sequences leaking in.
+ assert "\x1b[" not in out
+ assert "[/" not in out
+ assert out.strip() == json.dumps(json.loads(out), indent=2)
+
+ def test_run_default_output_is_human_not_json(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF_DONE, "done2")
+ result = self._invoke(project_dir, ["workflow", "run", str(wf)])
+ assert result.exit_code == 0
+ assert "Running workflow" in result.stdout
+ with pytest.raises(json.JSONDecodeError):
+ json.loads(result.stdout)
+
+ def test_json_redirect_keeps_stdout_clean(self, capfd):
+ # While a workflow runs under --json, steps can still write to stdout:
+ # the gate step prints its prompt and the prompt step runs a
+ # subprocess that inherits the stdout fd. Both must be redirected to
+ # stderr so the JSON object on stdout stays parseable. capfd captures
+ # at the file-descriptor level, so it sees the subprocess output too.
+ import subprocess
+ import sys as _sys
+ from specify_cli.workflows._commands import _stdout_to_stderr_when
+
+ print("STDOUT_BEFORE")
+ with _stdout_to_stderr_when(True):
+ print("PY_LEAK") # Python-level write (gate-style)
+ subprocess.run( # inherited-fd write (prompt-style)
+ [_sys.executable, "-c", "print('SUBPROC_LEAK')"],
+ check=True,
+ )
+ print("STDOUT_AFTER")
+
+ out, err = capfd.readouterr()
+ # stdout keeps only what was written outside the guarded block.
+ assert "STDOUT_BEFORE" in out and "STDOUT_AFTER" in out
+ assert "PY_LEAK" not in out and "SUBPROC_LEAK" not in out
+ # The step output is preserved on stderr, not discarded.
+ assert "PY_LEAK" in err and "SUBPROC_LEAK" in err
+
+ def test_json_redirect_inactive_is_noop(self, capfd):
+ from specify_cli.workflows._commands import _stdout_to_stderr_when
+
+ with _stdout_to_stderr_when(False):
+ print("VISIBLE_ON_STDOUT")
+ out, _ = capfd.readouterr()
+ assert "VISIBLE_ON_STDOUT" in out
+
+
+
+class TestWorkflowStepStartProgressLine:
+ """The `run`/`resume` step-progress line must render the step id literally.
+
+ The line is built as ` ▸ [<id>] <label> …`, so Rich parsed the bracketed id
+ as a style tag: it silently swallowed the id (the only identifying content
+ on the line), applied it as formatting when the id happened to be a real
+ style like `bold`, and raised MarkupError — failing the whole run — when the
+ id formed a closing tag such as `/`. `validate_workflow` places no charset
+ restriction on step ids, so all of these are accepted workflows.
+ """
+
+ def _write(self, tmp_path, step_id):
+ path = tmp_path / "wf.yml"
+ path.write_text(
+ 'schema_version: "1.0"\n'
+ "workflow:\n"
+ ' id: "probe-wf"\n'
+ ' name: "Probe"\n'
+ ' version: "1.0.0"\n'
+ "steps:\n"
+ f' - id: "{step_id}"\n'
+ " type: shell\n"
+ ' run: "exit 0"\n',
+ encoding="utf-8",
+ )
+ return path
+
+ @pytest.mark.parametrize("step_id", ["greet", "bold", "a]b"])
+ def test_progress_line_shows_step_id(self, tmp_path, monkeypatch, step_id):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ result = CliRunner().invoke(
+ app, ["workflow", "run", str(self._write(tmp_path, step_id))]
+ )
+ assert result.exit_code == 0, result.stdout
+ assert f"[{step_id}]" in result.stdout
+
+ def test_step_id_forming_a_closing_tag_does_not_fail_the_run(
+ self, tmp_path, monkeypatch
+ ):
+ """`id: "/"` raised MarkupError from inside the progress callback, which
+ surfaced as a failed run with no step results."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ result = CliRunner().invoke(
+ app, ["workflow", "run", str(self._write(tmp_path, "/"))]
+ )
+ assert result.exit_code == 0, result.stdout
+ assert "Status: completed" in result.stdout
+ assert "[/]" in result.stdout
+
+
+
+class TestWorkflowRunExitCodes:
+ """CLI-level tests for the run/resume process exit codes."""
+
+ _WF_OK = """
+schema_version: "1.0"
+workflow:
+ id: "exit-ok"
+ name: "Exit OK"
+ version: "1.0.0"
+steps:
+ - id: fine
+ type: shell
+ run: "exit 0"
+"""
+
+ _WF_FAIL = """
+schema_version: "1.0"
+workflow:
+ id: "exit-fail"
+ name: "Exit Fail"
+ version: "1.0.0"
+steps:
+ - id: boom
+ type: shell
+ run: "exit 1"
+"""
+
+ def _write(self, tmp_path, content):
+ path = tmp_path / "wf.yml"
+ path.write_text(content, encoding="utf-8")
+ return path
+
+ _WF_GATE_INVALID_VERDICT = """
+schema_version: "1.0"
+workflow:
+ id: "gate-invalid-verdict"
+ name: "Gate Invalid Verdict"
+ version: "1.0.0"
+inputs:
+ review_verdict:
+ type: string
+ default: ""
+steps:
+ - id: review
+ type: gate
+ message: "Approve the review?"
+ options: [approve, reject]
+ on_reject: abort
+ verdict_input: review_verdict
+"""
+
+ _WF_GATE_INVALID_TYPE = """
+schema_version: "1.0"
+workflow:
+ id: "gate-invalid-type"
+ name: "Gate Invalid Type"
+ version: "1.0.0"
+inputs:
+ review_verdict:
+ type: number
+ default: 1
+steps:
+ - id: review
+ type: gate
+ message: "Approve the review?"
+ options: [approve, reject]
+ on_reject: abort
+ verdict_input: review_verdict
+"""
+
+ _WF_GATE_ABORT = """
+schema_version: "1.0"
+workflow:
+ id: "gate-abort"
+ name: "Gate Abort"
+ version: "1.0.0"
+inputs:
+ review_verdict:
+ type: string
+ default: ""
+steps:
+ - id: review
+ type: gate
+ message: "Approve the review?"
+ options: [approve, reject]
+ on_reject: abort
+ verdict_input: review_verdict
+"""
+
+ def test_run_completed_exits_zero(self, tmp_path, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "run", str(self._write(tmp_path, self._WF_OK))])
+ assert result.exit_code == 0
+ assert "Status: completed" in result.stdout
+
+ def test_run_failed_exits_nonzero(self, tmp_path, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL))])
+ assert "Status: failed" in result.stdout
+ assert result.exit_code == 1
+
+ def test_run_failed_exits_nonzero_with_json(self, tmp_path, monkeypatch):
+ import json as _json
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL)), "--json"],
+ )
+ assert result.exit_code == 1, result.stdout
+ payload = _json.loads(result.stdout)
+ assert payload["status"] == "failed"
+
+ def test_run_invalid_verdict_prints_error(self, tmp_path, monkeypatch):
+ """Invalid verdict value prints explanatory error in human output."""
+ import re
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ [
+ "workflow",
+ "run",
+ str(self._write(tmp_path, self._WF_GATE_INVALID_VERDICT)),
+ "--input",
+ "review_verdict=maybe",
+ ],
+ )
+ assert result.exit_code == 1
+ assert "Status: failed" in result.stdout
+ # Normalize whitespace to handle Rich console line wrapping
+ normalized = re.sub(r"\s+", " ", result.stdout)
+ assert "does not match any configured option" in normalized
+
+ def test_run_invalid_verdict_type_prints_error(self, tmp_path, monkeypatch):
+ """Non-string verdict value prints explanatory error in human output."""
+ import re
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ ["workflow", "run", str(self._write(tmp_path, self._WF_GATE_INVALID_TYPE))],
+ )
+ assert result.exit_code == 1
+ assert "Status: failed" in result.stdout
+ # Normalize whitespace to handle Rich console line wrapping
+ normalized = re.sub(r"\s+", " ", result.stdout)
+ assert "must be a string" in normalized
+
+ def test_run_gate_abort_prints_status_and_error(self, tmp_path, monkeypatch):
+ """Gate abort prints Status: aborted and the rejection message."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ [
+ "workflow",
+ "run",
+ str(self._write(tmp_path, self._WF_GATE_ABORT)),
+ "--input",
+ "review_verdict=reject",
+ ],
+ )
+ assert result.exit_code == 1
+ assert "Status: aborted" in result.stdout
+ assert "Gate rejected by user" in result.stdout
+
+ def test_run_gate_abort_json_includes_error(self, tmp_path, monkeypatch):
+ """Gate abort --json includes the rejection message in the error field."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(tmp_path)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ [
+ "workflow",
+ "run",
+ str(self._write(tmp_path, self._WF_GATE_ABORT)),
+ "--input",
+ "review_verdict=reject",
+ "--json",
+ ],
+ )
+ assert result.exit_code == 1
+ payload = json.loads(result.stdout)
+ assert payload["status"] == "aborted"
+ assert "Gate rejected by user" in (payload.get("error") or "")
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ _GATED_WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "gated-wf"
+ name: "Gated Workflow"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+"""
+
+ def test_run_refuses_falsy_non_bool_enabled(self, project_dir, monkeypatch):
+ """A falsy non-bool "enabled" (0) shows as disabled in list — run must agree."""
+ import json as json_mod
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ registry = WorkflowRegistry(project_dir)
+ registry.data["workflows"]["align-wf"]["enabled"] = 0
+ registry.registry_path.write_text(json_mod.dumps(registry.data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "run", "align-wf"])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ def test_run_rejects_corrupted_registry_entry(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ registry = WorkflowRegistry(project_dir)
+ registry.data["workflows"]["align-wf"] = "corrupted"
+ registry.save()
+
+ result = runner.invoke(app, ["workflow", "run", "align-wf"])
+ assert result.exit_code != 0
+ assert "corrupted" in result.output
+
+ def test_run_rejects_corrupt_registry_file(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.write_text("not json", encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "run", "align-wf"])
+
+ assert result.exit_code != 0
+ assert "registry" in result.output.lower()
+ assert "corrupt" in result.output.lower()
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_run_refuses_symlinked_specify_dir_hiding_disabled_workflow(
+ self, temp_dir, monkeypatch
+ ):
+ """A victim project's own .specify directory being a symlink to an
+ attacker-controlled tree must not bypass the disabled-workflow guard.
+ _reject_unsafe_workflow_storage only checks the *cwd's* project root
+ (unrelated here); the id/leaf symlink-component loop only checks
+ components from the id directory onward, missing .specify/
+ .specify/workflows themselves. The ownership check must reject an
+ unsafe .specify/.specify-workflows for the actual path-derived
+ registry root before ever consulting the registry -- it must not
+ rely on WorkflowRegistry's own symlinked-parent handling, which
+ raises a generic OSError; the ownership guard should surface the
+ specific unsafe-storage error before registry construction."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ victim = temp_dir / "victim"
+ victim.mkdir()
+ attacker_real = temp_dir / "attacker-real"
+ (attacker_real / "workflows" / "evil").mkdir(parents=True)
+ (attacker_real / "workflows" / "evil" / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ (attacker_real / "workflows" / "workflow-registry.json").write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ "evil": {
+ "name": "Evil",
+ "version": "1.0.0",
+ "source": "dev",
+ "enabled": False,
+ }
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+ (victim / ".specify").symlink_to(attacker_real)
+
+ unrelated_cwd = temp_dir / "unrelated-cwd"
+ unrelated_cwd.mkdir()
+ monkeypatch.chdir(unrelated_cwd)
+
+ runner = CliRunner()
+ target = victim / ".specify" / "workflows" / "evil" / "workflow.yml"
+ result = runner.invoke(app, ["workflow", "run", str(target)])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "symlink" in result.output.lower()
+
+ def test_run_nested_installed_paths_uses_nearest_owner(
+ self, temp_dir, monkeypatch
+ ):
+ """A direct workflow.yml path whose lexical segments contain
+ .specify/workflows more than once (an unrelated nested project
+ happens to live beneath an outer installed workflow's own
+ directory tree, reusing the same segment names) must be attributed
+ to its *nearest* (innermost) owning project/ID -- scanning from the
+ start of the path and stopping at the first match would pick the
+ outer project and the wrong workflow ID, gating the run on an
+ unrelated workflow's disabled state instead of the real owner's."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ def _write_registry(workflows_dir, workflow_id, enabled):
+ workflows_dir.mkdir(parents=True, exist_ok=True)
+ (workflows_dir / "workflow-registry.json").write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ workflow_id: {
+ "name": workflow_id,
+ "version": "1.0.0",
+ "source": "dev",
+ "enabled": enabled,
+ }
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ outer_workflows = temp_dir / "outer-proj" / ".specify" / "workflows"
+ outer_wf_dir = outer_workflows / "outer-wf"
+ outer_wf_dir.mkdir(parents=True)
+ (outer_wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ _write_registry(outer_workflows, "outer-wf", enabled=False)
+
+ # An unrelated nested project lives inside the outer workflow's own
+ # directory tree, with its own separate installed workflow.
+ inner_workflows = outer_wf_dir / "nested-proj" / ".specify" / "workflows"
+ inner_wf_dir = inner_workflows / "inner-wf"
+ inner_wf_dir.mkdir(parents=True)
+ (inner_wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ _write_registry(inner_workflows, "inner-wf", enabled=True)
+
+ unrelated_cwd = temp_dir / "unrelated-cwd"
+ unrelated_cwd.mkdir()
+ monkeypatch.chdir(unrelated_cwd)
+
+ runner = CliRunner()
+ target = inner_wf_dir / "workflow.yml"
+ result = runner.invoke(app, ["workflow", "run", str(target)])
+ # inner-wf (the actual nearest owner) is enabled -- must run, not
+ # be blocked by the unrelated outer-wf's disabled state.
+ assert result.exit_code == 0, result.output
+
+ # The inverse proves this isn't just ignoring nesting: disabling
+ # the true (nearest) owner must actually block this exact path.
+ _write_registry(inner_workflows, "inner-wf", enabled=False)
+ result = runner.invoke(app, ["workflow", "run", str(target)])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_run_blocks_disabled_workflow_via_outward_alias_symlink(
+ self, project_dir, monkeypatch
+ ):
+ """The inverse of the existing inward-symlink case: a path with no
+ .specify/workflows segments at all (e.g. /tmp/alias.yml) that is
+ itself a symlink resolving *into* installed storage must still
+ receive the disabled check. Only checking the lexical path's own
+ segments misses this alias entirely, since it has no such segments
+ to begin with, and would let engine.load_workflow follow the
+ symlink to the disabled workflow's real content unchecked."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+
+ result = runner.invoke(app, ["workflow", "disable", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ installed_yaml = (
+ project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ )
+ external_dir = project_dir / "outside-alias"
+ external_dir.mkdir()
+ alias = external_dir / "alias.yml"
+ alias.symlink_to(installed_yaml)
+
+ result = runner.invoke(app, ["workflow", "run", str(alias)])
+ assert result.exit_code != 0
+ assert "disabled" in result.output
+
+ result = runner.invoke(app, ["workflow", "enable", "align-wf"])
+ assert result.exit_code == 0, result.output
+ result = runner.invoke(app, ["workflow", "run", str(alias)])
+ assert result.exit_code == 0, result.output
+
+ def test_unregistered_workflow_shaped_path_is_not_persisted_as_owner(
+ self, project_dir, temp_dir, monkeypatch
+ ):
+ """A direct file is not installed merely because its path resembles
+ installed storage; only registry membership establishes ownership."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ standalone_root = temp_dir / "standalone-project"
+ workflows_dir = standalone_root / ".specify" / "workflows"
+ workflow_file = workflows_dir / "gated-wf" / "workflow.yml"
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_ids = []
+ for _ in range(2):
+ result = runner.invoke(
+ app, ["workflow", "run", str(workflow_file), "--json"]
+ )
+ assert result.exit_code == 0, result.output
+ run_ids.append(json.loads(result.stdout)["run_id"])
+
+ for run_id in run_ids:
+ state_path = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "runs"
+ / run_id
+ / "state.json"
+ )
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ assert state["installed_workflow_id"] is None
+ assert state["installed_registry_root"] is None
+
+ shutil.rmtree(standalone_root)
+ result = runner.invoke(
+ app, ["workflow", "resume", run_ids[0], "--json"]
+ )
+ assert result.exit_code == 0, result.output
+
+ workflows_dir.mkdir(parents=True)
+ (workflows_dir / "workflow-registry.json").write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ "gated-wf": {
+ "name": "Unrelated workflow",
+ "version": "9.9.9",
+ "source": "dev",
+ "enabled": False,
+ }
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+ result = runner.invoke(
+ app, ["workflow", "resume", run_ids[1], "--json"]
+ )
+ assert result.exit_code == 0, result.output
+
+
+class TestWorkflowRunWithoutProject:
+ """Tests that specify workflow run works with YAML files without .specify/ dir."""
+
+ def test_workflow_run_yaml_without_project(self, tmp_path):
+ """Running a .yml file should work without a .specify/ directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ # Create a minimal workflow YAML with a shell step
+ workflow_file = tmp_path / "test-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "standalone-test",
+ "name": "Standalone Test",
+ "version": "1.0.0",
+ "description": "A workflow that runs without a project",
+ },
+ "steps": [
+ {
+ "id": "create-marker",
+ "type": "shell",
+ "run": "echo done > marker.txt",
+ },
+ ],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+ assert result.exit_code == 0, f"workflow run failed: {result.output}"
+ assert "completed" in result.output
+ assert (tmp_path / "marker.txt").exists()
+ assert (tmp_path / ".specify" / "workflows" / "runs").is_dir()
+
+ def test_workflow_run_yaml_with_tilde_and_uppercase_suffix(self, tmp_path, monkeypatch):
+ """Running ~/file.YML should work without a .specify/ directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ home_dir = tmp_path / "home"
+ home_dir.mkdir()
+ monkeypatch.setenv("HOME", str(home_dir))
+ monkeypatch.setenv("USERPROFILE", str(home_dir))
+
+ workflow_file = home_dir / "test-workflow.YML"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "standalone-test-uppercase",
+ "name": "Standalone Test Uppercase",
+ "version": "1.0.0",
+ "description": "A workflow that runs from ~/ with an uppercase suffix",
+ },
+ "steps": [
+ {
+ "id": "create-marker",
+ "type": "shell",
+ "run": "echo done > marker.txt",
+ },
+ ],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", "~/test-workflow.YML",
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+ assert result.exit_code == 0, f"workflow run failed: {result.output}"
+ assert "Status: completed" in result.output
+ assert (tmp_path / "marker.txt").exists()
+
+ def test_workflow_run_id_still_requires_project(self, tmp_path):
+ """Running a workflow by ID should still require a .specify/ directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", "some-workflow-id",
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+ assert result.exit_code != 0
+ assert "Not a Spec Kit project" in result.output
+
+ def test_workflow_run_missing_yaml_file(self, tmp_path):
+ """Running a non-existent .yml file should still require a project."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", "nonexistent.yml",
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+ # non-existent .yml files fall through to project check or file-not-found
+ assert result.exit_code != 0
+
+ def test_workflow_run_failing_yaml_without_project(self, tmp_path):
+ """A failing workflow YAML should report failure status."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ workflow_file = tmp_path / "fail-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "fail-test",
+ "name": "Fail Test",
+ "version": "1.0.0",
+ "description": "A workflow that fails",
+ },
+ "steps": [
+ {
+ "id": "fail-step",
+ "type": "shell",
+ "run": "exit 1",
+ },
+ ],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+ # A failed workflow now maps to a non-zero process exit code so
+ # scripts and CI can rely on $? (the CLI itself still ran fine).
+ assert result.exit_code == 1, f"expected exit 1 on failed run: {result.output}"
+ assert "Status: failed" in result.output
+
+ def test_workflow_run_yaml_rejects_symlinked_specify_dir(self, tmp_path):
+ """Running local YAML should fail when .specify is a symlink."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ workflow_file = tmp_path / "test-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "symlink-test",
+ "name": "Symlink Test",
+ "version": "1.0.0",
+ "description": "A workflow for symlink guard testing",
+ },
+ "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ target_dir = tmp_path / "real-specify-dir"
+ target_dir.mkdir()
+ try:
+ (tmp_path / ".specify").symlink_to(target_dir, target_is_directory=True)
+ except (OSError, NotImplementedError):
+ pytest.skip("Symlinks are not available in this environment")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+
+ assert result.exit_code != 0
+ assert "Refusing to use symlinked .specify path" in result.output
+
+ def test_workflow_run_yaml_rejects_symlinked_workflows_dir(self, tmp_path):
+ """Running local YAML should fail when .specify/workflows is a symlink."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ workflow_file = tmp_path / "test-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "symlink-workflows-test",
+ "name": "Symlink Workflows Test",
+ "version": "1.0.0",
+ "description": "A workflow for symlink guard testing",
+ },
+ "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ (tmp_path / ".specify").mkdir()
+ target_dir = tmp_path / "real-workflows-dir"
+ target_dir.mkdir()
+ try:
+ (tmp_path / ".specify" / "workflows").symlink_to(
+ target_dir, target_is_directory=True
+ )
+ except (OSError, NotImplementedError):
+ pytest.skip("Symlinks are not available in this environment")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+
+ assert result.exit_code != 0
+ assert "Refusing to use symlinked .specify/workflows path" in result.output
+
+ def test_workflow_run_yaml_rejects_symlinked_runs_dir(self, tmp_path):
+ """Running local YAML should fail when .specify/workflows/runs is a symlink."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ workflow_file = tmp_path / "test-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "symlink-runs-test",
+ "name": "Symlink Runs Test",
+ "version": "1.0.0",
+ "description": "A workflow for symlink guard testing",
+ },
+ "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+ (tmp_path / ".specify" / "workflows").mkdir(parents=True)
+ target_dir = tmp_path / "real-runs-dir"
+ target_dir.mkdir()
+ try:
+ (tmp_path / ".specify" / "workflows" / "runs").symlink_to(
+ target_dir, target_is_directory=True
+ )
+ except (OSError, NotImplementedError):
+ pytest.skip("Symlinks are not available in this environment")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+
+ assert result.exit_code != 0
+ assert "Refusing to use symlinked .specify/workflows/runs path" in result.output
+
+ def test_workflow_run_yaml_rejects_non_directory_specify_path(self, tmp_path):
+ """Running local YAML should fail when .specify is not a directory."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ runner = CliRunner()
+
+ workflow_file = tmp_path / "test-workflow.yml"
+ workflow_content = {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "nondir-test",
+ "name": "Non-directory Test",
+ "version": "1.0.0",
+ "description": "A workflow for non-directory guard testing",
+ },
+ "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
+ }
+ workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+ (tmp_path / ".specify").write_text("not a directory", encoding="utf-8")
+
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(app, [
+ "workflow", "run", str(workflow_file),
+ ], catch_exceptions=False)
+ finally:
+ os.chdir(old_cwd)
+
+ assert result.exit_code != 0
+ assert ".specify path exists but is not a directory" in result.output
+
+
+
+class TestWorkflowRunJsonErrorStream:
+ """Under --json, error text must go to stderr so stdout stays parseable."""
+
+ def _bad_workflow(self, tmp_path):
+ wf = tmp_path / "bad.yml"
+ wf.write_text(
+ yaml.dump(
+ {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "bad-wf",
+ "name": "Bad",
+ "version": "1.0.0",
+ "description": "fails validation",
+ },
+ # shell step missing required 'run' -> validation error
+ "steps": [{"id": "s", "type": "shell"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ return wf
+
+ def test_run_json_validation_error_not_on_stdout(self, tmp_path):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ wf = self._bad_workflow(tmp_path)
+ runner = CliRunner()
+ old = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(
+ app, ["workflow", "run", str(wf), "--json"], catch_exceptions=False
+ )
+ finally:
+ os.chdir(old)
+
+ assert result.exit_code == 1
+ # stdout must carry only JSON (here: nothing) — never human error text.
+ assert "validation failed" not in result.stdout
+ assert "Error" not in result.stdout
+ # The message is routed to stderr instead.
+ assert "validation failed" in result.stderr
+
+ def test_run_json_invalid_input_not_on_stdout(self, tmp_path):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ # A valid single-shell workflow so we get past load/validate to
+ # _parse_input_values, which rejects the malformed --input.
+ wf = tmp_path / "ok.yml"
+ wf.write_text(
+ yaml.dump(
+ {
+ "schema_version": "1.0",
+ "workflow": {
+ "id": "ok-wf",
+ "name": "OK",
+ "version": "1.0.0",
+ "description": "x",
+ },
+ "steps": [{"id": "s", "type": "shell", "run": "echo hi"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ old = os.getcwd()
+ try:
+ os.chdir(tmp_path)
+ result = runner.invoke(
+ app,
+ ["workflow", "run", str(wf), "--json", "--input", "no-equals"],
+ catch_exceptions=False,
+ )
+ finally:
+ os.chdir(old)
+
+ assert result.exit_code == 1
+ assert "Invalid input format" not in result.stdout
+ assert "Invalid input format" in result.stderr
diff --git a/tests/specify_cli/workflows/test_command_run_ownership.py b/tests/specify_cli/workflows/test_command_run_ownership.py
new file mode 100644
index 000000000..c06695af4
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_run_ownership.py
@@ -0,0 +1,51 @@
+"""Tests for run-private installed workflow ownership."""
+
+import os
+import shutil
+
+import pytest
+import typer
+
+
+class TestWorkflowCliAlignment:
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_alias_rejects_symlinked_workflow_storage_before_resolve(
+ self, project_dir, temp_dir
+ ):
+ from specify_cli.workflows import _command_run_ownership as run_ownership
+
+ specify_dir = project_dir / ".specify"
+ shutil.rmtree(specify_dir)
+ redirected = temp_dir / "redirected-storage"
+ workflow_file = redirected / "workflows" / "evil" / "workflow.yml"
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ specify_dir.symlink_to(redirected, target_is_directory=True)
+ alias = temp_dir / "workflow-alias.yml"
+ alias.symlink_to(
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "evil"
+ / "workflow.yml"
+ )
+
+ with pytest.raises(typer.Exit):
+ run_ownership._resolve_installed_workflow_ownership(
+ alias, run_ownership.cli.err_console
+ )
diff --git a/tests/specify_cli/workflows/test_command_search.py b/tests/specify_cli/workflows/test_command_search.py
new file mode 100644
index 000000000..2afdb19b8
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_search.py
@@ -0,0 +1,96 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ def test_search_author_filters(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ workflows = {
+ "wf-a": {"name": "Workflow A", "version": "1.0.0", "description": "", "author": "alice"},
+ "wf-b": {"name": "Workflow B", "version": "1.0.0", "description": "", "author": "bob"},
+ }
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "_get_merged_workflows",
+ lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "search", "--author", "Alice"])
+ assert result.exit_code == 0, result.output
+ assert "wf-a" in result.output
+ assert "wf-b" not in result.output
+
+ def test_search_escapes_rich_markup_in_catalog_fields(self, project_dir, monkeypatch):
+ """Catalog-derived name/description/tags must not be parsed as Rich markup."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ workflows = {
+ "wf-a": {
+ "name": "Bracket [Search]",
+ "version": "1.0.0",
+ "description": "desc [with] brackets",
+ "tags": ["tag[1]", "tag2"],
+ },
+ }
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "_get_merged_workflows",
+ lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "search"])
+ assert result.exit_code == 0, result.output
+ assert "Bracket [Search]" in result.output
+ assert "desc [with] brackets" in result.output
+ assert "tag[1]" in result.output
+
+ def test_search_and_info_tolerate_non_list_tags(self, project_dir, monkeypatch):
+ """A scalar ``tags:`` value must not crash the search/info display.
+
+ ``WorkflowCatalog.search`` guards its tag *filter* with
+ ``isinstance(raw_tags, list)``, but the ``workflow search`` and
+ ``workflow info`` display paths only tested truthiness before
+ iterating. ``tags: 5`` is truthy and not iterable, so both raised
+ ``TypeError: 'int' object is not iterable``.
+ """
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ workflows = {
+ "wf-a": {
+ "name": "Workflow A",
+ "version": "1.0.0",
+ "description": "desc",
+ "tags": 5,
+ },
+ }
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "_get_merged_workflows",
+ lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
+ )
+ runner = CliRunner()
+ searched = runner.invoke(app, ["workflow", "search"])
+ info = runner.invoke(app, ["workflow", "info", "wf-a"])
+
+ assert searched.exit_code == 0, searched.output
+ assert "Workflow A" in searched.output
+ assert "Tags:" not in searched.output
+
+ assert info.exit_code == 0, info.output
+ assert "Tags:" not in info.output
diff --git a/tests/specify_cli/workflows/test_command_status.py b/tests/specify_cli/workflows/test_command_status.py
new file mode 100644
index 000000000..0a7b50ac1
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_status.py
@@ -0,0 +1,295 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+import typer
+
+
+
+class TestWorkflowJsonOutput:
+ """Test the --json machine-readable output for run/resume/status."""
+
+ _WF = """
+schema_version: "1.0"
+workflow:
+ id: "json-wf"
+ name: "JSON WF"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+ - id: after
+ type: shell
+ run: "echo done"
+"""
+
+ _WF_FAIL = """
+schema_version: "1.0"
+workflow:
+ id: "json-fail"
+ name: "JSON Fail"
+ version: "1.0.0"
+steps:
+ - id: boom
+ type: shell
+ run: "exit 3"
+"""
+
+ def _write_wf(self, project_dir, text, name):
+ path = project_dir / f"{name}.yml"
+ path.write_text(text, encoding="utf-8")
+ return path
+
+ def _invoke(self, project_dir, args):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ return runner.invoke(app, args, catch_exceptions=False)
+
+ def test_status_json_failed_includes_error(self, project_dir):
+ # `status --json` reuses the shared payload, so a failed run inspected
+ # after the fact surfaces the same error text as `run`/`resume`.
+ wf = self._write_wf(project_dir, self._WF_FAIL, "boom2")
+ rid = json.loads(
+ self._invoke(
+ project_dir, ["workflow", "run", str(wf), "--json"]
+ ).stdout
+ )["run_id"]
+ status = json.loads(
+ self._invoke(
+ project_dir, ["workflow", "status", rid, "--json"]
+ ).stdout
+ )
+ assert status["status"] == "failed"
+ assert status.get("error")
+
+ def test_status_json_single_and_list(self, project_dir):
+ wf = self._write_wf(project_dir, self._WF, "gated2")
+ run = json.loads(
+ self._invoke(project_dir, ["workflow", "run", str(wf), "--json"]).stdout
+ )
+ rid = run["run_id"]
+
+ single = json.loads(
+ self._invoke(project_dir, ["workflow", "status", rid, "--json"]).stdout
+ )
+ assert single["run_id"] == rid
+ assert single["status"] == "paused"
+ assert single["steps"]["ask"] == "paused"
+ # status --json carries the same step-position fields as run/resume
+ # so automation never has to branch on which command produced it.
+ assert single["current_step_id"] == run["current_step_id"]
+ assert single["current_step_index"] == run["current_step_index"]
+
+ listing = json.loads(
+ self._invoke(project_dir, ["workflow", "status", "--json"]).stdout
+ )
+ assert any(r["run_id"] == rid for r in listing["runs"])
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ _GATED_WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "gated-wf"
+ name: "Gated Workflow"
+ version: "1.0.0"
+steps:
+ - id: ask
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+"""
+
+ def _install_and_run_gated(self, runner, app, project_dir):
+ """Install a gate-step workflow and run it to a paused state.
+
+ Returns the run_id. The gate step pauses without any interactive
+ input, giving a resumable run tied to an installed workflow ID.
+ """
+ src = project_dir / "gated-src"
+ src.mkdir(exist_ok=True)
+ (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+
+ result = runner.invoke(app, ["workflow", "run", "gated-wf", "--json"])
+ assert result.exit_code == 0, result.output
+ payload = json.loads(result.stdout)
+ assert payload["status"] == "paused"
+ return payload["run_id"]
+
+ @pytest.mark.parametrize(
+ "field, bad_value",
+ [
+ ("installed_workflow_id", 123),
+ ("installed_workflow_id", ["gated-wf"]),
+ ("installed_registry_root", 123),
+ ("installed_registry_root", ["."]),
+ ],
+ )
+ def test_status_rejects_malformed_run_state_origin_fields(
+ self, project_dir, monkeypatch, field, bad_value
+ ):
+ """`workflow status <run_id>` calls RunState.load() same as resume,
+ but only caught FileNotFoundError -- the new type validation there
+ (int/list instead of str-or-null) raises ValueError, which leaked
+ as a raw unhandled traceback instead of `workflow resume`'s clean
+ `[red]Error:[/red] {exc}` + exit 1. Must get the identical clean
+ boundary, leaving the no-run-id list path (and FileNotFoundError
+ behavior) unchanged."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ run_id = self._install_and_run_gated(runner, app, project_dir)
+
+ state_path = (
+ project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
+ )
+ data = json.loads(state_path.read_text(encoding="utf-8"))
+ data[field] = bad_value
+ state_path.write_text(json.dumps(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "status", run_id])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Error" in result.output
+
+ def test_status_run_not_found_unchanged(self, project_dir, monkeypatch):
+ """FileNotFoundError behavior for a nonexistent run_id must remain
+ exactly as before this fix."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "status", "nonexistent-run"])
+ assert result.exit_code != 0
+ assert "Run not found: nonexistent-run" in result.output
+
+ def test_status_json_not_found_error_goes_to_stderr(
+ self, project_dir, monkeypatch, capsys
+ ):
+ """Under --json, the not-found/invalid-run error must go to stderr so the
+ stdout JSON stream stays parseable (empty on the error path) — mirroring
+ `workflow run`/`workflow resume`. Before this fix both handlers used the
+ stdout console, corrupting a consumer's json.loads(stdout)."""
+ from specify_cli.workflows import _commands
+
+ (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
+ monkeypatch.setattr(
+ _commands, "_require_specify_project", lambda: project_dir
+ )
+ with pytest.raises(typer.Exit) as exc:
+ _commands.workflow_status("does-not-exist", json_output=True)
+ assert exc.value.exit_code == 1
+ captured = capsys.readouterr()
+ assert "Run not found" in captured.err
+ assert "Run not found" not in captured.out
+ # stdout carries no partial/corrupt JSON on the error path.
+ assert captured.out.strip() == ""
+
+ def test_status_json_invalid_run_error_goes_to_stderr(
+ self, project_dir, monkeypatch, capsys
+ ):
+ """The ValueError handler (a malformed/invalid run state) must ALSO route
+ to stderr under --json, not just the FileNotFoundError one — otherwise a
+ regression there would silently corrupt the JSON stream and this suite
+ wouldn't catch it."""
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.engine import RunState
+
+ (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
+ monkeypatch.setattr(
+ _commands, "_require_specify_project", lambda: project_dir
+ )
+
+ def _raise_value_error(*args, **kwargs):
+ raise ValueError("corrupt run state: bad status")
+
+ monkeypatch.setattr(RunState, "load", _raise_value_error)
+
+ with pytest.raises(typer.Exit) as exc:
+ _commands.workflow_status("some-run", json_output=True)
+ assert exc.value.exit_code == 1
+ captured = capsys.readouterr()
+ assert "corrupt run state" in captured.err
+ assert "corrupt run state" not in captured.out
+ assert captured.out.strip() == ""
+
+ def test_status_unreadable_run_state_exits_cleanly(
+ self, project_dir, monkeypatch
+ ):
+ """`workflow status <run_id>` gained a ValueError boundary to match
+ `workflow resume`, but not resume's OSError one -- so an unreadable
+ state.json (bad permissions, a directory in its place, an I/O error)
+ still leaked a raw traceback. exists() is True for a directory, so
+ the guard passes and open() raises OSError."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runs_dir = project_dir / ".specify" / "workflows" / "runs" / "abc123"
+ runs_dir.mkdir(parents=True, exist_ok=True)
+ # A directory where state.json should be: exists() passes, open() fails.
+ (runs_dir / "state.json").mkdir(exist_ok=True)
+
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "status", "abc123"])
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Error" in result.output
+
+ def test_status_json_unreadable_run_state_error_goes_to_stderr(
+ self, project_dir, monkeypatch, capsys
+ ):
+ """The OSError handler must route to stderr under --json too, so the
+ stdout JSON stream stays parseable -- mirroring the sibling
+ FileNotFoundError/ValueError handlers."""
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.engine import RunState
+
+ (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
+ monkeypatch.setattr(
+ _commands, "_require_specify_project", lambda: project_dir
+ )
+
+ def _raise_os_error(*args, **kwargs):
+ raise PermissionError(13, "Permission denied")
+
+ monkeypatch.setattr(RunState, "load", _raise_os_error)
+
+ with pytest.raises(typer.Exit) as exc:
+ _commands.workflow_status("some-run", json_output=True)
+ assert exc.value.exit_code == 1
+ captured = capsys.readouterr()
+ assert "Permission denied" in captured.err
+ assert "Permission denied" not in captured.out
+ assert captured.out.strip() == ""
+
+ def test_status_no_run_id_list_path_unaffected(self, project_dir, monkeypatch):
+ """The no-run-id list-all-runs path must remain unaffected by the
+ new single-run ValueError boundary."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "status"])
+ assert result.exit_code == 0, result.output
diff --git a/tests/specify_cli/workflows/test_command_update.py b/tests/specify_cli/workflows/test_command_update.py
new file mode 100644
index 000000000..b0f2d29e6
--- /dev/null
+++ b/tests/specify_cli/workflows/test_command_update.py
@@ -0,0 +1,801 @@
+"""Command-focused workflow tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+import pytest
+
+
+
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
+
+ WORKFLOW_YAML = """
+schema_version: "1.0"
+workflow:
+ id: "align-wf"
+ name: "Align Workflow"
+ version: "{version}"
+ description: "CLI alignment test workflow"
+steps:
+ - id: step-one
+ type: shell
+ run: "echo hello"
+"""
+
+ def _write_workflow_dir(self, base, version="1.0.0"):
+ d = base / "wf-src"
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
+ )
+ return d
+
+ def _install_dev(self, runner, app, project_dir):
+ src = self._write_workflow_dir(project_dir)
+ result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
+ assert result.exit_code == 0, result.output
+ return src
+
+ class _FakeResponse:
+ def __init__(self, data, url="https://example.com/workflow.yml", headers=None):
+ self._data = data
+ self._url = url
+ self._pos = 0
+ self._headers = headers or {}
+
+ def read(self, amt=None):
+ if amt is None:
+ chunk = self._data[self._pos :]
+ self._pos = len(self._data)
+ return chunk
+ chunk = self._data[self._pos : self._pos + amt]
+ self._pos += len(chunk)
+ return chunk
+
+ def getheader(self, name, default=None):
+ return self._headers.get(name, default)
+
+ def geturl(self):
+ return self._url
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def test_update_no_workflows_installed(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "No workflows installed" in result.output
+
+ def test_update_not_installed_errors(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update", "ghost"])
+ assert result.exit_code != 0
+ assert "not installed" in result.output
+
+ def test_update_skips_non_catalog_sources(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir)
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "re-add to update" in result.output
+ # Every target was skipped — must not claim everything is up to date.
+ assert "No workflows were eligible for update" in result.output
+ assert "up to date!" not in result.output
+
+ def test_update_skip_message_accurate_for_bundled_source(self, project_dir, monkeypatch):
+ """A workflow registered with source "bundled" (e.g. the speckit
+ workflow installed by `specify init`) was never installed from a
+ local path or URL; the skip message must not claim otherwise."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add(
+ "speckit",
+ {"name": "Speckit", "version": "1.0.0", "source": "bundled"},
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "local path or URL" not in result.output
+ assert "re-add to update" in result.output
+
+ def test_update_mixed_targets_does_not_claim_all_up_to_date(self, project_dir, monkeypatch):
+ """Skipped targets must not be presented as verified up to date."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ runner = CliRunner()
+ self._install_dev(runner, app, project_dir) # local source → skipped
+ WorkflowRegistry(project_dir).add("catalog-wf", {
+ "name": "Catalog Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ },
+ )
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "All workflows are up to date!" not in result.output
+ assert "All checked workflows are up to date" in result.output
+ assert "skipped" in result.output
+
+ def test_update_installs_newer_catalog_version(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "CLI alignment test workflow",
+ "source": "catalog",
+ "catalog_name": "test-catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ wf_dir.mkdir(parents=True)
+ (wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert result.exit_code == 0, result.output
+ assert "1.0.0" in result.output and "2.0.0" in result.output
+ meta = WorkflowRegistry(project_dir).get("align-wf")
+ assert meta["version"] == "2.0.0"
+ assert "2.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
+
+ def test_update_downloaded_invalid_yaml_escapes_rich_markup(self, project_dir, monkeypatch):
+ """A malformed downloaded workflow can quote the offending line verbatim; escape it before printing."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+ from specify_cli.workflows.engine import WorkflowDefinition
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "CLI alignment test workflow",
+ "source": "catalog",
+ "catalog_name": "test-catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ wf_dir.mkdir(parents=True)
+ (wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(b"", url),
+ ), patch.object(
+ WorkflowDefinition,
+ "from_string",
+ side_effect=ValueError('bad snippet: "New [Feature]"'),
+ ):
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert 'bad snippet: "New [Feature]"' in result.output
+ assert "Failed to update" in result.output
+ # The previously installed workflow must survive a failed update.
+ assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
+
+ def test_update_malformed_catalog_url_fails_cleanly(self, project_dir, monkeypatch):
+ """An unparseable catalog URL (unbalanced IPv6 literal) must not abort the whole update."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "CLI alignment test workflow",
+ "source": "catalog",
+ "catalog_name": "test-catalog",
+ "url": "https://[::1/workflow.yml",
+ })
+ wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ wf_dir.mkdir(parents=True)
+ (wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://[::1/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert "malformed install URL" in result.output
+ assert "Failed to update" in result.output
+ # The previously installed workflow must survive.
+ assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
+
+ def test_update_rejects_version_mismatch_from_stale_url(self, project_dir, monkeypatch):
+ """A URL serving a different version than the catalog advertised must fail the update."""
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ WorkflowRegistry(project_dir).add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "CLI alignment test workflow",
+ "source": "catalog",
+ "catalog_name": "test-catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ wf_dir.mkdir(parents=True)
+ (wf_dir / "workflow.yml").write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ # The URL still serves the old 1.0.0 payload.
+ data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert "does not match the catalog version" in result.output
+ assert "Failed to update" in result.output
+ meta = WorkflowRegistry(project_dir).get("align-wf")
+ assert meta["version"] == "1.0.0"
+ assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
+
+ def test_update_preserves_disabled_state(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ WorkflowRegistry(project_dir).add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ "enabled": False,
+ })
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ runner = CliRunner()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert result.exit_code == 0, result.output
+ meta = WorkflowRegistry(project_dir).get("align-wf")
+ assert meta["version"] == "2.0.0"
+ assert meta["enabled"] is False
+
+ @pytest.mark.skipif(os.name == "nt", reason="POSIX permission bits")
+ def test_update_preserves_workflow_file_mode(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ WorkflowRegistry(project_dir).add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ workflow_file = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "align-wf"
+ / "workflow.yml"
+ )
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ workflow_file.chmod(0o640)
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ },
+ )
+ data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(data, url),
+ ):
+ result = CliRunner().invoke(
+ app, ["workflow", "update"], input="y\n"
+ )
+
+ assert result.exit_code == 0, result.output
+ assert stat.S_IMODE(workflow_file.stat().st_mode) == 0o640
+
+ def test_update_skips_corrupted_registry_entry(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(
+ json.dumps({"schema_version": "1.0", "workflows": {"broken": "not-a-dict"}}),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "corrupted" in result.output
+
+ def test_update_reports_unsafe_registry_id_per_workflow(self, project_dir, monkeypatch):
+ """An unsafe workflow id in the registry must fail that one entry, not abort the whole update."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowRegistry, WorkflowCatalog
+
+ monkeypatch.chdir(project_dir)
+ registry_path = WorkflowRegistry(project_dir).registry_path
+ registry_path.parent.mkdir(parents=True, exist_ok=True)
+ registry_path.write_text(
+ json.dumps(
+ {
+ "schema_version": "1.0",
+ "workflows": {
+ "../evil": {
+ "name": "Bad",
+ "version": "0.0.1",
+ "source": "catalog",
+ "url": "https://example.com/evil.yml",
+ },
+ },
+ }
+ ),
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {"version": "9.9.9", "url": "https://example.com/evil.yml", "_install_allowed": True},
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert result.exit_code != 0
+ assert "Failed to update" in result.output
+
+ def test_update_registry_save_failure_restores_prior_file_without_redundant_write(
+ self, project_dir, monkeypatch
+ ):
+ """A registry.add() save failure during `workflow update` must be
+ fully restored by _install_workflow_from_catalog's own atomic
+ rollback (rename-based, not a byte-level rewrite). The outer
+ workflow_update loop must not perform any redundant write of its
+ own onto the destination file -- that write happened only after
+ typer.Exit already unwound, could itself fail/truncate the safely
+ preserved file, and is provably unnecessary here since the inner
+ transaction already restored it via rename."""
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ runner = CliRunner()
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ source_data, url
+ ),
+ )
+ result = runner.invoke(app, ["workflow", "add", "align-wf"])
+ assert result.exit_code == 0, result.output
+
+ dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
+ original_data = dest_file.read_bytes()
+
+ new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+
+ def boom_save(self):
+ raise OSError("disk full")
+
+ dest_writes: list[bytes] = []
+ real_write_bytes = Path.write_bytes
+ resolved_dest_file = dest_file.resolve()
+
+ def tracking_write_bytes(self_path, data, *args, **kwargs):
+ if self_path.resolve() == resolved_dest_file:
+ dest_writes.append(data)
+ return real_write_bytes(self_path, data, *args, **kwargs)
+
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ mp.setattr(
+ "specify_cli.authentication.http.open_url",
+ lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
+ new_data, url
+ ),
+ )
+ mp.setattr(WorkflowRegistry, "save", boom_save)
+ mp.setattr(Path, "write_bytes", tracking_write_bytes)
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+
+ assert result.exit_code != 0
+ assert "Failed to update" in result.output
+ # No redundant/second write of the destination file was attempted --
+ # the inner atomic commit/rollback (rename-based) is the only thing
+ # that ever touches it.
+ assert dest_writes == []
+ assert dest_file.read_bytes() == original_data
+ registry = WorkflowRegistry(project_dir)
+ assert registry.is_installed("align-wf")
+ assert registry.get("align-wf")["version"] == "1.0.0"
+
+ def test_update_non_json_description_restores_prior_file_and_registry(
+ self, project_dir, monkeypatch
+ ):
+ from unittest.mock import patch
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add(
+ "align-wf",
+ {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ },
+ )
+ workflow_file = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "align-wf"
+ / "workflow.yml"
+ )
+ workflow_file.parent.mkdir(parents=True)
+ original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
+ workflow_file.write_bytes(original_data)
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+ invalid_data = self.WORKFLOW_YAML.format(version="2.0.0").replace(
+ 'description: "CLI alignment test workflow"',
+ "description: 2026-01-02",
+ ).encode()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(invalid_data, url),
+ ):
+ result = CliRunner().invoke(
+ app, ["workflow", "update", "align-wf"], input="y\n"
+ )
+
+ assert result.exit_code != 0
+ assert result.exception is None or isinstance(result.exception, SystemExit)
+ assert "Failed to update workflow registry" in result.output
+ assert workflow_file.read_bytes() == original_data
+ current = WorkflowRegistry(project_dir).get("align-wf")
+ assert current["version"] == "1.0.0"
+ leftovers = [
+ path.name
+ for path in workflow_file.parent.iterdir()
+ if path.name != "workflow.yml"
+ ]
+ assert leftovers == []
+
+ @pytest.mark.parametrize(
+ ("replacement_source", "replacement_version"),
+ [("local", "1.0.0"), ("catalog", "1.5.0")],
+ )
+ def test_update_rechecks_registry_after_confirmation(
+ self, project_dir, monkeypatch, replacement_source, replacement_version
+ ):
+ from unittest.mock import patch
+
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows import _commands
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ registry = WorkflowRegistry(project_dir)
+ registry.add(
+ "align-wf",
+ {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ },
+ )
+ workflow_file = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "align-wf"
+ / "workflow.yml"
+ )
+ workflow_file.parent.mkdir(parents=True)
+ workflow_file.write_text(
+ self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
+ )
+ replacement_data = self.WORKFLOW_YAML.format(
+ version=replacement_version
+ ).replace(
+ 'description: "CLI alignment test workflow"',
+ 'description: "concurrent replacement"',
+ ).encode()
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "name": "Align Workflow",
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ "_catalog_name": "test-catalog",
+ },
+ )
+
+ def replace_while_confirming(*args, **kwargs):
+ WorkflowRegistry(project_dir).add(
+ "align-wf",
+ {
+ "name": "Concurrent replacement",
+ "version": replacement_version,
+ "description": "",
+ "source": replacement_source,
+ },
+ )
+ workflow_file.write_bytes(replacement_data)
+ return True
+
+ monkeypatch.setattr(_commands.typer, "confirm", replace_while_confirming)
+ catalog_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
+ with patch(
+ "specify_cli.authentication.http.open_url",
+ side_effect=lambda url, timeout=None, extra_headers=None,
+ redirect_validator=None: self._FakeResponse(catalog_data, url),
+ ):
+ result = CliRunner().invoke(app, ["workflow", "update", "align-wf"])
+
+ assert result.exit_code != 0
+ assert "changed during update" in result.output
+ assert workflow_file.read_bytes() == replacement_data
+ current = WorkflowRegistry(project_dir).get("align-wf")
+ assert current["source"] == replacement_source
+ assert current["version"] == replacement_version
+
+ def test_update_up_to_date_reports_and_exits_zero(self, project_dir, monkeypatch):
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ WorkflowRegistry(project_dir).add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "version": "1.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ },
+ )
+ runner = CliRunner()
+ result = runner.invoke(app, ["workflow", "update"])
+ assert result.exit_code == 0, result.output
+ assert "Up to date" in result.output
+ assert "All workflows are up to date!" in result.output
+
+ def test_update_restores_backup_on_failed_download(self, project_dir, monkeypatch):
+ from unittest.mock import patch
+ from typer.testing import CliRunner
+ from specify_cli import app
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
+
+ monkeypatch.chdir(project_dir)
+ WorkflowRegistry(project_dir).add("align-wf", {
+ "name": "Align Workflow",
+ "version": "1.0.0",
+ "description": "",
+ "source": "catalog",
+ "url": "https://example.com/workflow.yml",
+ })
+ wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
+ wf_dir.mkdir(parents=True)
+ original = self.WORKFLOW_YAML.format(version="1.0.0")
+ (wf_dir / "workflow.yml").write_text(original, encoding="utf-8")
+
+ monkeypatch.setattr(
+ WorkflowCatalog,
+ "get_workflow_info",
+ lambda self, wid: {
+ "id": wid,
+ "version": "2.0.0",
+ "url": "https://example.com/workflow.yml",
+ "_install_allowed": True,
+ },
+ )
+
+ def boom(url, timeout=None, extra_headers=None, redirect_validator=None):
+ raise OSError("network down")
+
+ runner = CliRunner()
+ with patch("specify_cli.authentication.http.open_url", side_effect=boom):
+ result = runner.invoke(app, ["workflow", "update"], input="y\n")
+ assert result.exit_code != 0
+ assert "Failed to update" in result.output
+ # Working copy and registry version are untouched
+ assert (wf_dir / "workflow.yml").read_text(encoding="utf-8") == original
+ assert WorkflowRegistry(project_dir).get("align-wf")["version"] == "1.0.0"
diff --git a/tests/test_commands_package.py b/tests/test_commands_package.py
index a92470264..fd42eb8b7 100644
--- a/tests/test_commands_package.py
+++ b/tests/test_commands_package.py
@@ -32,7 +32,7 @@ def test_script_type_choices_includes_python():
def test_workflow_init_valid_script_types_includes_python():
- from specify_cli.workflows.steps.init import VALID_SCRIPT_TYPES
+ from specify_cli.workflows.step.init import VALID_SCRIPT_TYPES
assert "py" in VALID_SCRIPT_TYPES
# Negative: an unknown variant is not accepted.
assert "rb" not in VALID_SCRIPT_TYPES
diff --git a/tests/test_workflow_run_without_project.py b/tests/test_workflow_run_without_project.py
deleted file mode 100644
index d9c741543..000000000
--- a/tests/test_workflow_run_without_project.py
+++ /dev/null
@@ -1,408 +0,0 @@
-"""Tests for running workflow YAML files without a project."""
-
-import os
-
-import pytest
-import yaml
-
-
-class TestWorkflowRunWithoutProject:
- """Tests that specify workflow run works with YAML files without .specify/ dir."""
-
- def test_workflow_run_yaml_without_project(self, tmp_path):
- """Running a .yml file should work without a .specify/ directory."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- # Create a minimal workflow YAML with a shell step
- workflow_file = tmp_path / "test-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "standalone-test",
- "name": "Standalone Test",
- "version": "1.0.0",
- "description": "A workflow that runs without a project",
- },
- "steps": [
- {
- "id": "create-marker",
- "type": "shell",
- "run": "echo done > marker.txt",
- },
- ],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
- assert result.exit_code == 0, f"workflow run failed: {result.output}"
- assert "completed" in result.output
- assert (tmp_path / "marker.txt").exists()
- assert (tmp_path / ".specify" / "workflows" / "runs").is_dir()
-
- def test_workflow_run_yaml_with_tilde_and_uppercase_suffix(self, tmp_path, monkeypatch):
- """Running ~/file.YML should work without a .specify/ directory."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- home_dir = tmp_path / "home"
- home_dir.mkdir()
- monkeypatch.setenv("HOME", str(home_dir))
- monkeypatch.setenv("USERPROFILE", str(home_dir))
-
- workflow_file = home_dir / "test-workflow.YML"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "standalone-test-uppercase",
- "name": "Standalone Test Uppercase",
- "version": "1.0.0",
- "description": "A workflow that runs from ~/ with an uppercase suffix",
- },
- "steps": [
- {
- "id": "create-marker",
- "type": "shell",
- "run": "echo done > marker.txt",
- },
- ],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", "~/test-workflow.YML",
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
- assert result.exit_code == 0, f"workflow run failed: {result.output}"
- assert "Status: completed" in result.output
- assert (tmp_path / "marker.txt").exists()
-
- def test_workflow_run_id_still_requires_project(self, tmp_path):
- """Running a workflow by ID should still require a .specify/ directory."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", "some-workflow-id",
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
- assert result.exit_code != 0
- assert "Not a Spec Kit project" in result.output
-
- def test_workflow_run_missing_yaml_file(self, tmp_path):
- """Running a non-existent .yml file should still require a project."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", "nonexistent.yml",
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
- # non-existent .yml files fall through to project check or file-not-found
- assert result.exit_code != 0
-
- def test_workflow_run_failing_yaml_without_project(self, tmp_path):
- """A failing workflow YAML should report failure status."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- workflow_file = tmp_path / "fail-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "fail-test",
- "name": "Fail Test",
- "version": "1.0.0",
- "description": "A workflow that fails",
- },
- "steps": [
- {
- "id": "fail-step",
- "type": "shell",
- "run": "exit 1",
- },
- ],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
- # A failed workflow now maps to a non-zero process exit code so
- # scripts and CI can rely on $? (the CLI itself still ran fine).
- assert result.exit_code == 1, f"expected exit 1 on failed run: {result.output}"
- assert "Status: failed" in result.output
-
- def test_workflow_run_yaml_rejects_symlinked_specify_dir(self, tmp_path):
- """Running local YAML should fail when .specify is a symlink."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- workflow_file = tmp_path / "test-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "symlink-test",
- "name": "Symlink Test",
- "version": "1.0.0",
- "description": "A workflow for symlink guard testing",
- },
- "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- target_dir = tmp_path / "real-specify-dir"
- target_dir.mkdir()
- try:
- (tmp_path / ".specify").symlink_to(target_dir, target_is_directory=True)
- except (OSError, NotImplementedError):
- pytest.skip("Symlinks are not available in this environment")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
-
- assert result.exit_code != 0
- assert "Refusing to use symlinked .specify path" in result.output
-
- def test_workflow_run_yaml_rejects_symlinked_workflows_dir(self, tmp_path):
- """Running local YAML should fail when .specify/workflows is a symlink."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- workflow_file = tmp_path / "test-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "symlink-workflows-test",
- "name": "Symlink Workflows Test",
- "version": "1.0.0",
- "description": "A workflow for symlink guard testing",
- },
- "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- (tmp_path / ".specify").mkdir()
- target_dir = tmp_path / "real-workflows-dir"
- target_dir.mkdir()
- try:
- (tmp_path / ".specify" / "workflows").symlink_to(
- target_dir, target_is_directory=True
- )
- except (OSError, NotImplementedError):
- pytest.skip("Symlinks are not available in this environment")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
-
- assert result.exit_code != 0
- assert "Refusing to use symlinked .specify/workflows path" in result.output
-
- def test_workflow_run_yaml_rejects_symlinked_runs_dir(self, tmp_path):
- """Running local YAML should fail when .specify/workflows/runs is a symlink."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- workflow_file = tmp_path / "test-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "symlink-runs-test",
- "name": "Symlink Runs Test",
- "version": "1.0.0",
- "description": "A workflow for symlink guard testing",
- },
- "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
-
- (tmp_path / ".specify" / "workflows").mkdir(parents=True)
- target_dir = tmp_path / "real-runs-dir"
- target_dir.mkdir()
- try:
- (tmp_path / ".specify" / "workflows" / "runs").symlink_to(
- target_dir, target_is_directory=True
- )
- except (OSError, NotImplementedError):
- pytest.skip("Symlinks are not available in this environment")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
-
- assert result.exit_code != 0
- assert "Refusing to use symlinked .specify/workflows/runs path" in result.output
-
- def test_workflow_run_yaml_rejects_non_directory_specify_path(self, tmp_path):
- """Running local YAML should fail when .specify is not a directory."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- runner = CliRunner()
-
- workflow_file = tmp_path / "test-workflow.yml"
- workflow_content = {
- "schema_version": "1.0",
- "workflow": {
- "id": "nondir-test",
- "name": "Non-directory Test",
- "version": "1.0.0",
- "description": "A workflow for non-directory guard testing",
- },
- "steps": [{"id": "noop", "type": "shell", "run": "echo done"}],
- }
- workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
- (tmp_path / ".specify").write_text("not a directory", encoding="utf-8")
-
- old_cwd = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(app, [
- "workflow", "run", str(workflow_file),
- ], catch_exceptions=False)
- finally:
- os.chdir(old_cwd)
-
- assert result.exit_code != 0
- assert ".specify path exists but is not a directory" in result.output
-
-
-class TestWorkflowRunJsonErrorStream:
- """Under --json, error text must go to stderr so stdout stays parseable."""
-
- def _bad_workflow(self, tmp_path):
- wf = tmp_path / "bad.yml"
- wf.write_text(
- yaml.dump(
- {
- "schema_version": "1.0",
- "workflow": {
- "id": "bad-wf",
- "name": "Bad",
- "version": "1.0.0",
- "description": "fails validation",
- },
- # shell step missing required 'run' -> validation error
- "steps": [{"id": "s", "type": "shell"}],
- }
- ),
- encoding="utf-8",
- )
- return wf
-
- def test_run_json_validation_error_not_on_stdout(self, tmp_path):
- from typer.testing import CliRunner
- from specify_cli import app
-
- wf = self._bad_workflow(tmp_path)
- runner = CliRunner()
- old = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(
- app, ["workflow", "run", str(wf), "--json"], catch_exceptions=False
- )
- finally:
- os.chdir(old)
-
- assert result.exit_code == 1
- # stdout must carry only JSON (here: nothing) — never human error text.
- assert "validation failed" not in result.stdout
- assert "Error" not in result.stdout
- # The message is routed to stderr instead.
- assert "validation failed" in result.stderr
-
- def test_run_json_invalid_input_not_on_stdout(self, tmp_path):
- from typer.testing import CliRunner
- from specify_cli import app
-
- # A valid single-shell workflow so we get past load/validate to
- # _parse_input_values, which rejects the malformed --input.
- wf = tmp_path / "ok.yml"
- wf.write_text(
- yaml.dump(
- {
- "schema_version": "1.0",
- "workflow": {
- "id": "ok-wf",
- "name": "OK",
- "version": "1.0.0",
- "description": "x",
- },
- "steps": [{"id": "s", "type": "shell", "run": "echo hi"}],
- }
- ),
- encoding="utf-8",
- )
- runner = CliRunner()
- old = os.getcwd()
- try:
- os.chdir(tmp_path)
- result = runner.invoke(
- app,
- ["workflow", "run", str(wf), "--json", "--input", "no-equals"],
- catch_exceptions=False,
- )
- finally:
- os.chdir(old)
-
- assert result.exit_code == 1
- assert "Invalid input format" not in result.stdout
- assert "Invalid input format" in result.stderr
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 197532a05..6c7545f21 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -18,9 +18,7 @@ import os
import shutil
import stat
import sys
-import tarfile
import tempfile
-import zipfile
from pathlib import Path
import pytest
@@ -126,7 +124,7 @@ class TestStepRegistry:
def test_register_step_duplicate_raises(self):
from specify_cli.workflows import _register_step
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
with pytest.raises(KeyError, match="already registered"):
_register_step(CommandStep())
@@ -1078,7 +1076,7 @@ class TestCommandStep:
def test_execute_basic(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1091,7 +1089,7 @@ class TestCommandStep:
"command": "speckit.specify",
"input": {"args": "{{ inputs.name }}"},
}
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.status == StepStatus.FAILED
assert result.output["command"] == "speckit.specify"
@@ -1102,7 +1100,7 @@ class TestCommandStep:
self, tmp_path, monkeypatch
):
from specify_cli.workflows.base import StepContext, StepStatus
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
calls = []
@@ -1200,7 +1198,7 @@ class TestCommandStep:
expected_model,
):
from specify_cli.workflows.base import StepContext, StepStatus
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
calls = []
@@ -1244,7 +1242,7 @@ class TestCommandStep:
def test_unsupported_runtime_config_fails_with_actionable_error(self):
from specify_cli.workflows.base import StepContext, StepStatus
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
result = CommandStep().execute(
{
@@ -1264,7 +1262,7 @@ class TestCommandStep:
assert "saftey" in (result.error or "")
def test_validate_rejects_malformed_runtime_config(self):
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
step = CommandStep()
errors = step.validate(
@@ -1295,7 +1293,7 @@ class TestCommandStep:
def test_try_dispatch_resolves_rovodev_via_acli(self, tmp_path):
"""When acli is installed, rovodev dispatch succeeds via acli."""
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1314,7 +1312,7 @@ class TestCommandStep:
mock_result.stdout = ""
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.command.shutil.which",
+ with patch("specify_cli.workflows.step.command.shutil.which",
lambda name: "/usr/bin/acli" if name == "acli" else None), \
patch("subprocess.run", return_value=mock_result):
result = step.execute(config, ctx)
@@ -1324,14 +1322,14 @@ class TestCommandStep:
assert result.output["exit_code"] == 0
def test_validate_missing_command(self):
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
step = CommandStep()
errors = step.validate({"id": "test"})
assert any("missing 'command'" in e for e in errors)
def test_validate_rejects_non_mapping_input_and_options(self):
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1366,7 +1364,7 @@ class TestCommandStep:
a validated run — and feeds 'model' into the CLI argv. Mirrors the
'command'/'input'/'options' type checks.
"""
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
step = CommandStep()
errs = step.validate({"id": "c", "command": "/x", "integration": bad})
@@ -1377,7 +1375,7 @@ class TestCommandStep:
def test_validate_accepts_none_and_expression_integration_model(self):
"""An explicit YAML-null (inherit default) or a '{{ ... }}' expression
integration/model stays valid — only literal non-strings are rejected."""
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
step = CommandStep()
assert step.validate(
@@ -1393,7 +1391,7 @@ class TestCommandStep:
) == []
def test_validate_rejects_non_string_command(self):
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
step = CommandStep()
# execute() passes 'command' to build_command_invocation(), which does
@@ -1408,7 +1406,7 @@ class TestCommandStep:
def test_execute_non_string_command_fails_cleanly(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1418,7 +1416,7 @@ class TestCommandStep:
# resolvable integration + installed CLI so, absent the guard, dispatch
# would actually be attempted and the crash would fire.
ctx = StepContext(default_integration="claude")
- with patch("specify_cli.workflows.steps.command.shutil.which",
+ with patch("specify_cli.workflows.step.command.shutil.which",
return_value="/usr/bin/claude"):
for bad in (None, ["a", "b"], 5, {"x": 1}):
result = step.execute(
@@ -1431,7 +1429,7 @@ class TestCommandStep:
"""On an unvalidated run, an unhashable 'integration' would crash
get_integration() (dict.get on a list) with a raw TypeError. execute()
must fail the step with the contract error instead."""
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1459,7 +1457,7 @@ class TestCommandStep:
configured default the step would silently dispatch using the wrong
integration instead of surfacing the contract error. The default is set
here so a regression dispatches rather than fails-not-possible."""
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1478,7 +1476,7 @@ class TestCommandStep:
def test_step_override_integration(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext
step = CommandStep()
@@ -1489,7 +1487,7 @@ class TestCommandStep:
"integration": "gemini",
"input": {},
}
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.output["integration"] == "gemini"
@@ -1497,7 +1495,7 @@ class TestCommandStep:
"""A non-string integration (e.g. a list from an expression that resolved
to one) must FAIL the step cleanly, not crash the run with
'TypeError: unhashable type: list' from get_integration's dict lookup."""
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1510,7 +1508,7 @@ class TestCommandStep:
def test_step_override_model(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext
step = CommandStep()
@@ -1521,13 +1519,13 @@ class TestCommandStep:
"model": "opus-4",
"input": {},
}
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.output["model"] == "opus-4"
def test_options_merge(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext
step = CommandStep()
@@ -1538,7 +1536,7 @@ class TestCommandStep:
"options": {"thinking-budget": 32768},
"input": {},
}
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.output["options"]["max-tokens"] == 8000
assert result.output["options"]["thinking-budget"] == 32768
@@ -1546,7 +1544,7 @@ class TestCommandStep:
def test_dispatch_not_attempted_without_cli(self):
"""When the CLI tool is not installed, step should fail."""
from unittest.mock import patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1560,7 +1558,7 @@ class TestCommandStep:
"command": "speckit.specify",
"input": {"args": "{{ inputs.name }}"},
}
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.status == StepStatus.FAILED
assert result.output["dispatched"] is False
@@ -1569,7 +1567,7 @@ class TestCommandStep:
def test_dispatch_with_mock_cli(self, tmp_path, monkeypatch):
"""When the CLI is installed, dispatch invokes the command by name."""
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1589,7 +1587,7 @@ class TestCommandStep:
mock_result.stdout = '{"result": "done"}'
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value="/usr/local/bin/claude"), \
patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
patch("subprocess.run", return_value=mock_result) as mock_run:
result = step.execute(config, ctx)
@@ -1609,7 +1607,7 @@ class TestCommandStep:
def test_dispatch_uses_executable_override_for_fallback_preflight(self, tmp_path, monkeypatch):
"""Command preflight falls back to build_exec_args() argv[0]."""
from unittest.mock import MagicMock, patch
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
@@ -1636,7 +1634,7 @@ class TestCommandStep:
mock_result.stdout = '{"result": "done"}'
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.command.shutil.which", side_effect=fake_which), \
+ with patch("specify_cli.workflows.step.command.shutil.which", side_effect=fake_which), \
patch("subprocess.run", return_value=mock_result) as mock_run:
result = step.execute(config, ctx)
@@ -1650,7 +1648,7 @@ class TestCommandStep:
def test_dispatch_failure_returns_failed_status(self, tmp_path):
"""When the CLI exits non-zero, the step should fail."""
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.command import CommandStep
+ from specify_cli.workflows.step.command import CommandStep
from specify_cli.workflows.base import StepContext, StepStatus
step = CommandStep()
@@ -1670,7 +1668,7 @@ class TestCommandStep:
mock_result.stdout = ""
mock_result.stderr = "API error"
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value="/usr/local/bin/claude"), \
patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \
patch("subprocess.run", return_value=mock_result):
result = step.execute(config, ctx)
@@ -1685,7 +1683,7 @@ class TestPromptStep:
def test_execute_basic(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1698,7 +1696,7 @@ class TestPromptStep:
"type": "prompt",
"prompt": "Review {{ inputs.file }} for security issues",
}
- with patch("specify_cli.workflows.steps.prompt.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.status == StepStatus.FAILED
assert result.output["prompt"] == "Review auth.py for security issues"
@@ -1708,7 +1706,7 @@ class TestPromptStep:
def test_execute_non_string_integration_fails_cleanly(self):
"""A non-string integration must FAIL the step cleanly, not crash with
'TypeError: unhashable type: list' from get_integration's dict lookup."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1721,7 +1719,7 @@ class TestPromptStep:
def test_execute_with_step_integration(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext
step = PromptStep()
@@ -1732,13 +1730,13 @@ class TestPromptStep:
"prompt": "Summarize the codebase",
"integration": "gemini",
}
- with patch("specify_cli.workflows.steps.prompt.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.output["integration"] == "gemini"
def test_execute_with_model(self):
from unittest.mock import patch
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext
step = PromptStep()
@@ -1749,14 +1747,14 @@ class TestPromptStep:
"prompt": "hello",
"model": "opus-4",
}
- with patch("specify_cli.workflows.steps.prompt.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.prompt.shutil.which", return_value=None):
result = step.execute(config, ctx)
assert result.output["model"] == "opus-4"
def test_try_dispatch_resolves_rovodev_via_acli(self, tmp_path):
"""When acli is installed, rovodev prompt dispatch succeeds via acli."""
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1775,7 +1773,7 @@ class TestPromptStep:
mock_result.stdout = ""
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.prompt.shutil.which",
+ with patch("specify_cli.workflows.step.prompt.shutil.which",
lambda name: "/usr/bin/acli" if name == "acli" else None), \
patch("subprocess.run", return_value=mock_result):
result = step.execute(config, ctx)
@@ -1795,7 +1793,7 @@ class TestPromptStep:
IntegrationBase.dispatch_command -- resolves argv[0] and works.
"""
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1809,7 +1807,7 @@ class TestPromptStep:
mock_result.stderr = ""
with patch(
- "specify_cli.workflows.steps.prompt.shutil.which",
+ "specify_cli.workflows.step.prompt.shutil.which",
lambda name: resolved,
), patch("subprocess.run", return_value=mock_result) as run:
result = step.execute(config, ctx)
@@ -1821,7 +1819,7 @@ class TestPromptStep:
def test_dispatch_with_mock_cli(self, tmp_path):
from unittest.mock import patch, MagicMock
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1840,7 +1838,7 @@ class TestPromptStep:
mock_result.stdout = "Here is the explanation"
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.prompt.shutil.which", return_value="/usr/local/bin/claude"), \
+ with patch("specify_cli.workflows.step.prompt.shutil.which", return_value="/usr/local/bin/claude"), \
patch("subprocess.run", return_value=mock_result):
result = step.execute(config, ctx)
@@ -1851,7 +1849,7 @@ class TestPromptStep:
def test_dispatch_uses_executable_override_for_fallback_preflight(self, tmp_path, monkeypatch):
"""Prompt preflight falls back to build_exec_args() argv[0]."""
from unittest.mock import MagicMock, patch
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
monkeypatch.setenv("SPECKIT_INTEGRATION_CLAUDE_EXECUTABLE", "/opt/claude")
@@ -1877,7 +1875,7 @@ class TestPromptStep:
mock_result.stdout = "Here is the explanation"
mock_result.stderr = ""
- with patch("specify_cli.workflows.steps.prompt.shutil.which", side_effect=fake_which), \
+ with patch("specify_cli.workflows.step.prompt.shutil.which", side_effect=fake_which), \
patch("subprocess.run", return_value=mock_result) as mock_run:
result = step.execute(config, ctx)
@@ -1889,7 +1887,7 @@ class TestPromptStep:
assert call_args[0][0][2] == "Explain this code"
def test_validate_missing_prompt(self):
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errors = step.validate({"id": "test"})
@@ -1904,14 +1902,14 @@ class TestPromptStep:
the model as instructions — silently wrong. Mirrors the shell-step
'run' type check.
"""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errors = step.validate({"id": "p", "prompt": bad_prompt})
assert any("'prompt' must be a string" in e for e in errors)
def test_validate_valid(self):
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errors = step.validate({"id": "test", "prompt": "do something"})
@@ -1919,7 +1917,7 @@ class TestPromptStep:
def test_validate_accepts_expression_prompt(self):
"""A '{{ ... }}' expression prompt is a str, so it stays valid."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errors = step.validate(
@@ -1934,7 +1932,7 @@ class TestPromptStep:
execute() passes 'integration' to get_integration(), which uses it as a
dict key — an unhashable list/dict raises a raw TypeError there, even on
a validated run — and feeds 'model' into the CLI argv."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errs = step.validate({"id": "p", "prompt": "hi", "integration": bad})
@@ -1945,7 +1943,7 @@ class TestPromptStep:
def test_validate_accepts_none_and_expression_integration_model(self):
"""An explicit YAML-null (inherit default) or a '{{ ... }}' expression
integration/model stays valid — only literal non-strings are rejected."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
assert step.validate(
@@ -1964,7 +1962,7 @@ class TestPromptStep:
"""On an unvalidated run, an unhashable 'integration' would crash
get_integration() (dict.get on a dict) with a raw TypeError. execute()
must fail the step with the contract error instead."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -1990,7 +1988,7 @@ class TestPromptStep:
configured default the step would silently dispatch using the wrong
integration instead of surfacing the contract error. The default is set
here so a regression dispatches rather than fails-not-possible."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
step = PromptStep()
@@ -2018,7 +2016,7 @@ class TestPromptStep:
``subprocess.run()`` — raise ``OverflowError``, so the guard has to
catch that rather than let it escape as the crash it exists to stop.
"""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
errors = step.validate(
@@ -2032,7 +2030,7 @@ class TestPromptStep:
@pytest.mark.parametrize("good", [300, 5, 0.5])
def test_validate_accepts_valid_timeout(self, good):
"""A positive int/float timeout — and an absent one — stay valid."""
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
for config in (
@@ -2055,7 +2053,7 @@ class TestPromptStep:
import subprocess
from unittest.mock import patch
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
from specify_cli.workflows.base import StepContext, StepStatus
def fail_if_called(*args, **kwargs):
@@ -2071,7 +2069,7 @@ class TestPromptStep:
# too large to convert to float raises OverflowError.
for bad in ("30", True, float("nan"), 0, -5, ["30"], 10**400):
with patch(
- "specify_cli.workflows.steps.prompt.shutil.which",
+ "specify_cli.workflows.step.prompt.shutil.which",
return_value="/opt/claude",
):
result = step.execute(
@@ -2093,7 +2091,7 @@ class TestPromptStep:
from unittest.mock import MagicMock, patch
from specify_cli.workflows.base import StepContext
- from specify_cli.workflows.steps.prompt import PromptStep
+ from specify_cli.workflows.step.prompt import PromptStep
step = PromptStep()
ctx = StepContext(project_root="/fake/project/root", default_integration="dummy")
@@ -2109,7 +2107,7 @@ class TestPromptStep:
mock_result.stderr = ""
with patch("specify_cli.integrations.get_integration", mock_get_integration), \
- patch("specify_cli.workflows.steps.prompt.shutil.which", return_value="/opt/dummy"), \
+ patch("specify_cli.workflows.step.prompt.shutil.which", return_value="/opt/dummy"), \
patch("subprocess.run", return_value=mock_result):
step.execute(
{"id": "p", "type": "prompt", "prompt": "hi", "integration": "dummy"},
@@ -2139,7 +2137,7 @@ class TestShellStep:
return f'"{sys.executable}" "{script}"'
def test_execute_echo(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
step = ShellStep()
@@ -2151,7 +2149,7 @@ class TestShellStep:
assert "hello" in result.output["stdout"]
def test_execute_failure(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
step = ShellStep()
@@ -2163,7 +2161,7 @@ class TestShellStep:
assert result.error is not None
def test_validate_missing_run(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
errors = step.validate({"id": "test"})
@@ -2176,21 +2174,21 @@ class TestShellStep:
execute() str()-coerces run and invokes it under shell=True, so a
null or list run would otherwise run the Python repr as a command.
"""
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
errors = step.validate({"id": "s", "run": bad_run})
assert any("'run' must be a string" in e for e in errors)
def test_validate_accepts_string_and_expression_run(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
assert step.validate({"id": "s", "run": "echo hi"}) == []
assert step.validate({"id": "s", "run": "{{ steps.x.output }}"}) == []
def test_output_format_json_exposes_data(self, tmp_path):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
step = ShellStep()
@@ -2208,7 +2206,7 @@ class TestShellStep:
assert result.output["exit_code"] == 0 # raw keys still present
def test_output_format_json_invalid_stdout_fails(self, tmp_path):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
step = ShellStep()
@@ -2223,7 +2221,7 @@ class TestShellStep:
assert "output_format: json" in (result.error or "")
def test_no_output_format_keeps_raw_output_only(self, tmp_path):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
step = ShellStep()
@@ -2239,7 +2237,7 @@ class TestShellStep:
assert "data" not in result.output
def test_validate_rejects_unknown_output_format(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
errors = step.validate({"id": "emit", "run": "exit 0", "output_format": "yaml"})
@@ -2250,7 +2248,7 @@ class TestShellStep:
threaded through to ``subprocess.run`` (issue #3327)."""
import subprocess
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
captured: dict[str, object] = {}
@@ -2273,7 +2271,7 @@ class TestShellStep:
"""Omitting ``timeout:`` preserves the historical 300s default."""
import subprocess
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext
captured: dict[str, object] = {}
@@ -2294,7 +2292,7 @@ class TestShellStep:
hardcoded 300."""
import subprocess
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
def fake_run(*args, **kwargs):
@@ -2315,7 +2313,7 @@ class TestShellStep:
otherwise crash subprocess.run() and take down the whole run."""
import subprocess
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
def fail_if_called(*args, **kwargs):
@@ -2333,7 +2331,7 @@ class TestShellStep:
assert "'timeout' must be a positive number" in (result.error or "")
def test_validate_rejects_non_positive_timeout(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
for bad in (0, -30):
@@ -2341,7 +2339,7 @@ class TestShellStep:
assert any("'timeout' must be a positive number" in e for e in errors)
def test_validate_rejects_non_numeric_timeout(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
# A string and a bool are both invalid (bool is an int subclass but a
@@ -2351,7 +2349,7 @@ class TestShellStep:
assert any("'timeout' must be a positive number" in e for e in errors)
def test_validate_rejects_non_finite_timeout(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
# inf/nan are floats and slip past a plain ``> 0`` check (``nan <= 0``
@@ -2375,7 +2373,7 @@ class TestShellStep:
value is genuinely invalid rather than merely unrepresentable here.
The prompt step already catches this (PR #3847).
"""
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
for bad in (10**400, -(10**400)):
@@ -2415,7 +2413,7 @@ class TestShellStep:
"""
import subprocess
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
from specify_cli.workflows.base import StepContext, StepStatus
def fail_if_called(*args, **kwargs):
@@ -2431,7 +2429,7 @@ class TestShellStep:
assert "'timeout' must be a positive number" in (result.error or ""), bad
def test_validate_accepts_positive_numeric_timeout(self):
- from specify_cli.workflows.steps.shell import ShellStep
+ from specify_cli.workflows.step.shell import ShellStep
step = ShellStep()
for good in (1, 300, 1800, 12.5):
@@ -2471,7 +2469,7 @@ class _FakeSys:
def _force_gate_stdin(monkeypatch, *, tty: bool):
- from specify_cli.workflows.steps import gate as gate_module
+ from specify_cli.workflows.step import gate as gate_module
monkeypatch.setattr(gate_module, "sys", _FakeSys(tty=tty))
@@ -2482,13 +2480,13 @@ class TestInitStep:
def test_docstring_lists_every_valid_script_type(self):
# The `script` field docstring must not contradict the step's own
# VALID_SCRIPT_TYPES (which includes 'py'); validate() accepts all three.
- from specify_cli.workflows.steps.init import InitStep, VALID_SCRIPT_TYPES
+ from specify_cli.workflows.step.init import InitStep, VALID_SCRIPT_TYPES
for script_type in VALID_SCRIPT_TYPES:
assert f"``{script_type}``" in InitStep.__doc__
def test_builds_here_argv_and_bootstraps(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2519,7 +2517,7 @@ class TestInitStep:
which ``_resolve_bool`` turned into False, dropping the flag and
re-enabling the agent-CLI presence check for an unattended run.
"""
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2541,7 +2539,7 @@ class TestInitStep:
def test_explicit_false_ignore_agent_tools_is_honoured(self, tmp_path):
"""An explicit ``false`` must still opt in to the agent-CLI check."""
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext
step = InitStep()
@@ -2561,7 +2559,7 @@ class TestInitStep:
assert "--ignore-agent-tools" not in result.output["argv"]
def test_default_integration_falls_back_to_workflow_default(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2578,7 +2576,7 @@ class TestInitStep:
# With no step-level and no workflow-level default, the resolved
# SPECKIT_INTEGRATION_DEFAULT value must drive both output.integration
# and the argv passed to init (guards against reverting to the constant).
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
monkeypatch.setenv("SPECKIT_INTEGRATION_DEFAULT", "gemini")
@@ -2593,7 +2591,7 @@ class TestInitStep:
assert "--integration" in argv and "gemini" in argv
def test_project_name_creates_subdirectory(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2612,7 +2610,7 @@ class TestInitStep:
assert (tmp_path / "demo" / ".specify").is_dir()
def test_invalid_integration_fails(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2631,7 +2629,7 @@ class TestInitStep:
assert result.error is not None
def test_non_empty_current_dir_without_force_fails_fast(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
(tmp_path / "existing.txt").write_text("data")
@@ -2649,7 +2647,7 @@ class TestInitStep:
assert not (tmp_path / ".specify").exists()
def test_engine_owned_dirs_do_not_trigger_non_empty_check(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
# Simulate the engine creating its run-state directory before steps run
@@ -2670,7 +2668,7 @@ class TestInitStep:
assert "--force" in result.output["argv"]
def test_default_integration_when_none_provided(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2684,7 +2682,7 @@ class TestInitStep:
assert result.output["integration"] == "copilot"
def test_integration_options_passed_through(self, tmp_path):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
from specify_cli.workflows.base import StepContext, StepStatus
step = InitStep()
@@ -2707,14 +2705,14 @@ class TestInitStep:
assert result.output["integration_options"] == "--skills"
def test_validate_rejects_bad_script(self):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
step = InitStep()
errors = step.validate({"id": "bootstrap", "script": "bogus"})
assert any("'script' must be 'sh' or 'ps'" in e for e in errors)
def test_validate_accepts_valid(self):
- from specify_cli.workflows.steps.init import InitStep
+ from specify_cli.workflows.step.init import InitStep
step = InitStep()
assert step.validate({"id": "bootstrap", "script": "sh"}) == []
@@ -2727,7 +2725,7 @@ class TestGateStep:
# The docstring must not contradict validate()/execute(): on_reject
# accepts 'abort', 'skip', AND 'retry' (execute() has a dedicated
# retry -> PAUSED branch), but the summary omitted 'retry'.
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
for behaviour in ("abort", "skip", "retry"):
assert behaviour in GateStep.__doc__
@@ -2741,7 +2739,7 @@ class TestGateStep:
_force_gate_stdin(monkeypatch, tty=False)
def test_execute_returns_paused(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
step = GateStep()
@@ -2761,7 +2759,7 @@ class TestGateStep:
"inputs", [{}, {"spec_verdict": None}, {"spec_verdict": ""}]
)
def test_missing_or_empty_verdict_input_uses_existing_pause_behavior(self, inputs):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
result = GateStep().execute(
@@ -2778,7 +2776,7 @@ class TestGateStep:
@pytest.mark.parametrize("inputs", [{}, {"spec_verdict": ""}])
def test_missing_or_empty_verdict_input_prompts_on_tty(self, monkeypatch, inputs):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
_force_gate_stdin(monkeypatch, tty=True)
@@ -2798,7 +2796,7 @@ class TestGateStep:
assert result.output["choice"] == "approve"
def test_verdict_input_uses_canonical_option_spelling(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
result = GateStep().execute(
@@ -2818,7 +2816,7 @@ class TestGateStep:
[(42, "must be a string"), ("maybe", "does not match")],
)
def test_invalid_verdict_input_value_fails(self, value, error_fragment):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
result = GateStep().execute(
@@ -2834,7 +2832,7 @@ class TestGateStep:
assert error_fragment in (result.error or "")
def test_verdict_input_fails_inside_fan_out_context(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
result = GateStep().execute(
@@ -2896,7 +2894,7 @@ steps:
@pytest.mark.parametrize("invalid_value", ["", 42, None])
def test_validate_invalid_verdict_input(self, invalid_value):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
errors = GateStep().validate({
"id": "review",
@@ -2916,7 +2914,7 @@ steps:
def test_reject_verdict_input_preserves_reject_behavior(
self, on_reject, status, aborted
):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext
context = StepContext(inputs={"spec_verdict": "reject"})
@@ -2937,14 +2935,14 @@ steps:
)
def test_validate_missing_message(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
step = GateStep()
errors = step.validate({"id": "test", "options": ["approve"]})
assert any("missing 'message'" in e for e in errors)
def test_validate_invalid_on_reject(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
step = GateStep()
errors = step.validate({
@@ -2968,7 +2966,7 @@ steps:
verb, a non-string, or a bare ``on_reject:`` (which yields None, since
``config.get(k, default)`` does not replace an explicit null).
"""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
result = GateStep().execute(
@@ -2989,7 +2987,7 @@ steps:
error, not crash: the reject-choice check calls o.lower() on each option,
which previously raised AttributeError on a non-string option and broke
validate_workflow's 'return errors, never raise' contract."""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
step = GateStep()
# on_reject defaults to "abort", which triggers the option-text check.
@@ -3002,7 +3000,7 @@ steps:
assert any("must be strings" in e for e in errors)
def test_interactive_prompt_renders_show_file(self, tmp_path, monkeypatch, capsys):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
review = tmp_path / "spec.md"
@@ -3030,7 +3028,7 @@ steps:
"""A Unicode digit int() can't parse — e.g. the superscript '²', which
str.isdigit() accepts but int() rejects — must be treated as an invalid
choice, not crash the prompt loop with an uncaught ValueError."""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
_force_gate_stdin(monkeypatch, tty=True)
inputs = iter(["²", "1"]) # superscript-two, then a real "1"
@@ -3042,7 +3040,7 @@ steps:
def test_interactive_prompt_missing_show_file_does_not_crash(
self, tmp_path, monkeypatch, capsys
):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
missing = tmp_path / "does-not-exist.md"
@@ -3066,7 +3064,7 @@ steps:
def test_non_interactive_show_file_still_pauses_without_reading(
self, tmp_path, monkeypatch
):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
review = tmp_path / "spec.md"
@@ -3096,14 +3094,14 @@ steps:
assert result.output["show_file"] == str(review)
def test_read_show_file_empty(self, tmp_path):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
empty = tmp_path / "empty.md"
empty.write_text("", encoding="utf-8")
assert GateStep._read_show_file(str(empty)) == ["(file is empty)"]
def test_read_show_file_truncates_large_file(self, tmp_path):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
big = tmp_path / "big.md"
big.write_text(
@@ -3116,7 +3114,7 @@ steps:
assert "truncated" in rendered[-1]
def test_read_show_file_invalid_path_does_not_raise(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
# An embedded NUL byte makes the OS reject the path with ValueError
# before any I/O; it must degrade to a notice, not crash the prompt.
@@ -3125,7 +3123,7 @@ steps:
assert rendered[0].startswith("(could not read file:")
def test_read_show_file_strips_control_chars(self, tmp_path):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
# A file with ANSI/control bytes must not inject escapes into the
# terminal; ESC and other C0 controls are stripped, tab is kept.
@@ -3136,7 +3134,7 @@ steps:
assert "\x1b" not in rendered[0] and "\x07" not in rendered[0]
def test_compose_prompt_sanitizes_show_file_path(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
# The displayed path header (and the read-error notice it produces)
# must not carry escapes even when the path string itself contains
@@ -3147,7 +3145,7 @@ steps:
assert "evil[2Jpath.md:" in out
def test_interactive_non_string_message_renders(self, monkeypatch, capsys):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
# A YAML numeric literal reaches the prompt as a non-string; it must
@@ -3163,7 +3161,7 @@ steps:
assert result.status == StepStatus.COMPLETED
def test_templated_show_file_resolving_to_non_string_is_coerced(self):
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
# A single-expression template can resolve to a non-string (e.g. a
@@ -3195,7 +3193,7 @@ steps:
``TypeError`` (``enumerate``/``len`` on a non-iterable) or ``KeyError``
(indexing a dict), crashing the whole workflow. Mirrors the switch
'cases' and command 'input' unvalidated-execute guards."""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
# Force an interactive TTY so the crash-prone _prompt path is reached;
@@ -3218,7 +3216,7 @@ steps:
would reach the reject test ``choice.lower()`` and raise a raw
``AttributeError`` at run time. ``validate`` reports "must be strings";
``execute`` must fail cleanly on an unvalidated run too."""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
_force_gate_stdin(monkeypatch, tty=True)
@@ -3237,7 +3235,7 @@ steps:
A malformed ``options`` should surface as FAILED in CI (non-TTY) rather
than PAUSING and only crashing later when an operator resumes on a real
terminal."""
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
from specify_cli.workflows.base import StepContext, StepStatus
# Autouse fixture already forces non-TTY stdin.
@@ -3253,7 +3251,7 @@ class TestIfThenStep:
"""Test the if/then/else step type."""
def test_execute_then_branch(self):
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
from specify_cli.workflows.base import StepContext
step = IfThenStep()
@@ -3270,7 +3268,7 @@ class TestIfThenStep:
assert result.next_steps[0]["id"] == "a"
def test_execute_else_branch(self):
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
from specify_cli.workflows.base import StepContext
step = IfThenStep()
@@ -3286,7 +3284,7 @@ class TestIfThenStep:
assert result.next_steps[0]["id"] == "b"
def test_validate_missing_condition(self):
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate({"id": "test", "then": []})
@@ -3298,7 +3296,7 @@ class TestIfThenStep:
# evaluate_expression, and evaluate_condition then bool()-coerces it, so
# it silently resolves to its truthiness (e.g. [1, 2] is always True)
# instead of erroring on the authoring mistake.
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate({"id": "test", "condition": bad, "then": []})
@@ -3313,7 +3311,7 @@ class TestIfThenStep:
],
)
def test_validate_accepts_string_or_bool_condition(self, good):
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate({"id": "test", "condition": good, "then": []})
@@ -3331,7 +3329,7 @@ class TestIfThenStep:
AttributeError on ``.get()``, taking down the whole run. Mirrors the
switch/fan-out non-list handling.
"""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
from specify_cli.workflows.base import StepContext, StepStatus
step = IfThenStep()
@@ -3351,7 +3349,7 @@ class TestIfThenStep:
condition is false, so a non-list ``else`` reaches ``next_steps`` and
would crash the engine's step iteration on an unvalidated run.
"""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
from specify_cli.workflows.base import StepContext, StepStatus
step = IfThenStep()
@@ -3371,7 +3369,7 @@ class TestIfThenStep:
normalize it to an empty branch (COMPLETED) rather than failing a
validator-approved workflow when the condition is false.
"""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
from specify_cli.workflows.base import StepContext, StepStatus
step = IfThenStep()
@@ -3391,7 +3389,7 @@ class TestIfThenStep:
malformed else-branch pass validation only to be silently skipped at
runtime. ``then`` is already strictly validated; ``else`` must match.
"""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate(
@@ -3406,7 +3404,7 @@ class TestIfThenStep:
``else`` is set explicitly here (including ``else: None``) so the
explicit-None case is exercised, not just the missing-key case.
"""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate(
@@ -3416,7 +3414,7 @@ class TestIfThenStep:
def test_validate_accepts_missing_else(self):
"""A missing 'else' key stays valid (no else branch)."""
- from specify_cli.workflows.steps.if_then import IfThenStep
+ from specify_cli.workflows.step.if_then import IfThenStep
step = IfThenStep()
errors = step.validate({"id": "i", "condition": "true", "then": []})
@@ -3435,7 +3433,7 @@ class TestSwitchStep:
while still reporting COMPLETED. There is no `trim` filter, so a
workflow author cannot strip it themselves.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext, StepStatus
config = {
@@ -3458,7 +3456,7 @@ class TestSwitchStep:
def test_execute_still_falls_through_for_a_genuine_mismatch(self):
"""Stripping must not make unrelated values match."""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext
config = {
@@ -3476,7 +3474,7 @@ class TestSwitchStep:
assert [s["id"] for s in result.next_steps] == ["fallback"]
def test_execute_matches_case(self):
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext
step = SwitchStep()
@@ -3497,7 +3495,7 @@ class TestSwitchStep:
assert result.next_steps[0]["id"] == "plan"
def test_execute_falls_to_default(self):
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext
step = SwitchStep()
@@ -3517,7 +3515,7 @@ class TestSwitchStep:
assert result.next_steps[0]["id"] == "fallback"
def test_execute_no_default_no_match(self):
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext
step = SwitchStep()
@@ -3545,7 +3543,7 @@ class TestSwitchStep:
AttributeError and took down the whole run instead of failing this step.
Mirrors the fan-out step's non-list ``items`` handling.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext, StepStatus
step = SwitchStep()
@@ -3576,7 +3574,7 @@ class TestSwitchStep:
``.get()``, taking down the whole run. Mirrors the non-mapping
``cases`` guard.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext, StepStatus
step = SwitchStep()
@@ -3603,7 +3601,7 @@ class TestSwitchStep:
case matches, so a non-list ``default`` reaches ``next_steps`` and would
crash the engine's step iteration on an unvalidated run.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext, StepStatus
step = SwitchStep()
@@ -3631,7 +3629,7 @@ class TestSwitchStep:
must normalize it to an empty branch (COMPLETED) rather than failing a
validator-approved workflow.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
from specify_cli.workflows.base import StepContext, StepStatus
step = SwitchStep()
@@ -3650,7 +3648,7 @@ class TestSwitchStep:
assert result.next_steps == (ok_default or [])
def test_validate_missing_expression(self):
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
step = SwitchStep()
errors = step.validate({"id": "test", "cases": {}})
@@ -3665,7 +3663,7 @@ class TestSwitchStep:
reported COMPLETED with `matched_case: "__default__"` having dispatched
nothing.
"""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
step = SwitchStep()
@@ -3681,7 +3679,7 @@ class TestSwitchStep:
def test_validate_accepts_an_empty_cases_mapping(self):
"""An explicitly declared but empty `cases:` is still a declaration."""
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
errors = SwitchStep().validate(
{"id": "route", "expression": "{{ inputs.x }}", "cases": {}}
@@ -3689,7 +3687,7 @@ class TestSwitchStep:
assert not any("missing 'cases'" in e for e in errors), errors
def test_validate_invalid_cases_and_default(self):
- from specify_cli.workflows.steps.switch import SwitchStep
+ from specify_cli.workflows.step.switch import SwitchStep
step = SwitchStep()
errors = step.validate({
@@ -3706,7 +3704,7 @@ class TestWhileStep:
"""Test the while loop step type."""
def test_execute_condition_true(self):
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
from specify_cli.workflows.base import StepContext
step = WhileStep()
@@ -3724,7 +3722,7 @@ class TestWhileStep:
assert len(result.next_steps) == 1
def test_execute_condition_false(self):
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
from specify_cli.workflows.base import StepContext
step = WhileStep()
@@ -3753,7 +3751,7 @@ class TestWhileStep:
the engine's step iteration on an unvalidated run. Mirrors the
if/switch/fan-out non-list handling.
"""
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
from specify_cli.workflows.base import StepContext, StepStatus
step = WhileStep()
@@ -3770,7 +3768,7 @@ class TestWhileStep:
"""A false condition never dispatches the body, so a non-list ``steps``
stays benign — the step completes without touching ``next_steps``.
"""
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
from specify_cli.workflows.base import StepContext, StepStatus
step = WhileStep()
@@ -3783,7 +3781,7 @@ class TestWhileStep:
assert result.next_steps == []
def test_validate_missing_fields(self):
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
step = WhileStep()
errors = step.validate({"id": "test", "steps": []})
@@ -3800,7 +3798,7 @@ class TestWhileStep:
never ran even once.
"""
from specify_cli.workflows.base import StepContext, StepStatus
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
step = WhileStep()
config = {
@@ -3819,7 +3817,7 @@ class TestWhileStep:
@pytest.mark.parametrize("bad", [["a", "b"], {"k": "v"}, 5, 1.5])
def test_validate_rejects_non_string_non_bool_condition(self, bad):
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
step = WhileStep()
errors = step.validate({"id": "test", "condition": bad, "steps": []})
@@ -3829,14 +3827,14 @@ class TestWhileStep:
def test_validate_accepts_string_or_bool_condition(self, good):
# ``condition: false`` unquoted is idiomatic YAML and is this step's own
# default, so a literal bool must not be rejected.
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
step = WhileStep()
errors = step.validate({"id": "test", "condition": good, "steps": []})
assert not any("'condition' must be a" in e for e in errors), good
def test_validate_invalid_max_iterations(self):
- from specify_cli.workflows.steps.while_loop import WhileStep
+ from specify_cli.workflows.step.while_loop import WhileStep
step = WhileStep()
errors = step.validate({"id": "test", "condition": "{{ true }}", "max_iterations": 0, "steps": []})
@@ -3853,7 +3851,7 @@ class TestDoWhileStep:
"""Test the do-while loop step type."""
def test_execute_always_runs_once(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
from specify_cli.workflows.base import StepContext
step = DoWhileStep()
@@ -3870,7 +3868,7 @@ class TestDoWhileStep:
assert result.output["condition"] == "{{ false }}"
def test_execute_with_true_condition(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
from specify_cli.workflows.base import StepContext
step = DoWhileStep()
@@ -3887,7 +3885,7 @@ class TestDoWhileStep:
assert result.output["max_iterations"] == 5
def test_validate_rejects_bool_max_iterations(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
# bool is an int subclass; `max_iterations: true` must be rejected.
@@ -3902,7 +3900,7 @@ class TestDoWhileStep:
assert ok == [], ok
def test_execute_empty_steps(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
from specify_cli.workflows.base import StepContext
step = DoWhileStep()
@@ -3929,7 +3927,7 @@ class TestDoWhileStep:
``next_steps`` and would crash the engine's step iteration on an
unvalidated run. Mirrors the if/switch/fan-out non-list handling.
"""
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
from specify_cli.workflows.base import StepContext, StepStatus
step = DoWhileStep()
@@ -3942,7 +3940,7 @@ class TestDoWhileStep:
assert result.next_steps == []
def test_validate_missing_fields(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
errors = step.validate({"id": "test", "steps": []})
@@ -3957,7 +3955,7 @@ class TestDoWhileStep:
then returned none, so the loop never ran even once.
"""
from specify_cli.workflows.base import StepContext, StepStatus
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
config = {"id": "refine", "condition": "true", "max_iterations": 3}
@@ -3970,7 +3968,7 @@ class TestDoWhileStep:
@pytest.mark.parametrize("bad", [["a", "b"], {"k": "v"}, 5, 1.5])
def test_validate_rejects_non_string_non_bool_condition(self, bad):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
errors = step.validate({"id": "test", "condition": bad, "steps": []})
@@ -3980,14 +3978,14 @@ class TestDoWhileStep:
def test_validate_accepts_string_or_bool_condition(self, good):
# ``condition: false`` unquoted is idiomatic YAML; evaluate_condition
# resolves a literal bool exactly, so it must not be rejected.
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
errors = step.validate({"id": "test", "condition": good, "steps": []})
assert not any("'condition' must be a" in e for e in errors), good
def test_validate_steps_not_list(self):
- from specify_cli.workflows.steps.do_while import DoWhileStep
+ from specify_cli.workflows.step.do_while import DoWhileStep
step = DoWhileStep()
errors = step.validate({
@@ -4003,7 +4001,7 @@ class TestFanOutStep:
"""Test the fan-out step type."""
def test_execute_with_items(self):
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
from specify_cli.workflows.base import StepContext
step = FanOutStep()
@@ -4024,7 +4022,7 @@ class TestFanOutStep:
assert result.output["max_concurrency"] == 3
def test_execute_non_list_items_fails_loudly(self):
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanOutStep()
@@ -4040,7 +4038,7 @@ class TestFanOutStep:
assert result.output["item_count"] == 0
def test_execute_empty_list_items_is_valid(self):
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanOutStep()
@@ -4065,7 +4063,7 @@ class TestFanOutStep:
AttributeError there and took down the whole run. Mirrors the fan-out
non-list ``items`` guard and the switch non-dict ``cases`` guard.
"""
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanOutStep()
@@ -4088,7 +4086,7 @@ class TestFanOutStep:
assert result.output["step_template"] == {}
def test_validate_missing_fields(self):
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
step = FanOutStep()
errors = step.validate({"id": "test"})
@@ -4096,7 +4094,7 @@ class TestFanOutStep:
assert any("missing 'step'" in e for e in errors)
def test_validate_step_not_mapping(self):
- from specify_cli.workflows.steps.fan_out import FanOutStep
+ from specify_cli.workflows.step.fan_out import FanOutStep
step = FanOutStep()
for bad_step in ("not-a-dict", ["impl"], 5, None):
@@ -4112,7 +4110,7 @@ class TestFanInStep:
"""Test the fan-in step type."""
def test_execute_collects_results(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext
step = FanInStep()
@@ -4131,7 +4129,7 @@ class TestFanInStep:
assert result.output["results"][0]["item_count"] == 2
def test_execute_multiple_wait_for(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext
step = FanInStep()
@@ -4152,7 +4150,7 @@ class TestFanInStep:
assert result.output["results"][1]["file"] == "b.md"
def test_execute_missing_wait_for_step(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext
step = FanInStep()
@@ -4178,7 +4176,7 @@ class TestFanInStep:
"silent empty result + COMPLETED" wiring bug the engine's fan-in
validation warns against. Mirrors the fan-out non-list ``items`` guard.
"""
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanInStep()
@@ -4202,7 +4200,7 @@ class TestFanInStep:
check even ran. The step still returned COMPLETED, so downstream
``steps.<id>.output.<key>`` resolved to None and interpolated as "".
"""
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanInStep()
@@ -4216,7 +4214,7 @@ class TestFanInStep:
def test_execute_explicit_null_output_stays_valid(self):
"""An explicit ``output:`` (YAML null) is valid, matching ``validate``."""
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanInStep()
@@ -4242,7 +4240,7 @@ class TestFanInStep:
list-shape guard exists to prevent. Mirrors the engine's
``test_non_string_wait_for_entry_is_rejected`` load-time check.
"""
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
from specify_cli.workflows.base import StepContext, StepStatus
step = FanInStep()
@@ -4255,14 +4253,14 @@ class TestFanInStep:
assert result.output["results"] == []
def test_validate_empty_wait_for(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
step = FanInStep()
errors = step.validate({"id": "test", "wait_for": []})
assert any("non-empty list" in e for e in errors)
def test_validate_wait_for_not_list(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
step = FanInStep()
errors = step.validate({"id": "test", "wait_for": "not-a-list"})
@@ -4272,7 +4270,7 @@ class TestFanInStep:
def test_validate_rejects_non_mapping_output(self, bad_output):
"""A non-mapping 'output' must be rejected: execute() would otherwise
silently coerce it to {} and drop the declared aggregation keys."""
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
step = FanInStep()
errors = step.validate(
@@ -4281,7 +4279,7 @@ class TestFanInStep:
assert any("'output' must be a mapping" in e for e in errors)
def test_validate_accepts_mapping_or_absent_output(self):
- from specify_cli.workflows.steps.fan_in import FanInStep
+ from specify_cli.workflows.step.fan_in import FanInStep
step = FanInStep()
assert step.validate(
@@ -5753,7 +5751,7 @@ steps:
"""
definition = WorkflowDefinition.from_string(yaml_str)
engine = WorkflowEngine(project_dir)
- with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ with patch("specify_cli.workflows.step.command.shutil.which", return_value=None):
state = engine.execute(definition, {"name": "login"})
assert state.status == RunStatus.FAILED
@@ -6811,7 +6809,7 @@ steps:
""")
engine = WorkflowEngine(project_dir)
with patch(
- "specify_cli.workflows.steps.command.shutil.which",
+ "specify_cli.workflows.step.command.shutil.which",
return_value=None,
):
state = engine.execute(definition, run_id="cafef00d")
@@ -7113,7 +7111,7 @@ steps:
from specify_cli.workflows.base import StepResult
with patch(
- "specify_cli.workflows.steps.gate.GateStep.execute",
+ "specify_cli.workflows.step.gate.GateStep.execute",
return_value=StepResult(output={"approved": True}),
):
state = engine.resume(state.run_id)
@@ -7419,7 +7417,7 @@ steps:
"""
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
from specify_cli.workflows.base import RunStatus
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
# Force the gate step into interactive mode and feed a "reject"
# choice so the abort path actually runs in the test env (default
@@ -7463,7 +7461,7 @@ steps:
"""
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine
from specify_cli.workflows.base import RunStatus
- from specify_cli.workflows.steps.gate import GateStep
+ from specify_cli.workflows.step.gate import GateStep
# `_prompt` echoes the option's original casing, so the operator
# picking "Reject" hands `execute` the capitalised string.
@@ -8328,7 +8326,8 @@ class TestWorkflowCatalog:
def test_non_mapping_cache_metadata_is_invalid(
self, project_dir, catalog_type
):
- from specify_cli.workflows.catalog import StepCatalog, WorkflowCatalog
+ from specify_cli.workflows.catalog import WorkflowCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog_cls = WorkflowCatalog if catalog_type == "workflow" else StepCatalog
catalog = catalog_cls(project_dir)
@@ -8392,12 +8391,8 @@ class TestWorkflowCatalog:
import io
from specify_cli.authentication import http as auth_http
- from specify_cli.workflows.catalog import (
- StepCatalog,
- StepCatalogEntry,
- WorkflowCatalog,
- WorkflowCatalogEntry,
- )
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowCatalogEntry
+ from specify_cli.workflows.step.catalog import StepCatalog, StepCatalogEntry
catalog_cls = WorkflowCatalog if catalog_type == "workflow" else StepCatalog
entry_cls = (
@@ -9047,7 +9042,7 @@ class TestStepRegistryCustom:
"""Test StepRegistry operations for custom step types."""
def test_add_and_get(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
registry.add("deploy", {"name": "Deploy", "version": "1.0.0", "type_key": "deploy"})
@@ -9058,7 +9053,7 @@ class TestStepRegistryCustom:
assert "installed_at" in entry
def test_add_does_not_mutate_input_metadata(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
metadata = {
@@ -9075,7 +9070,7 @@ class TestStepRegistryCustom:
assert registry.get("deploy")["nested"]["key"] == "original"
def test_remove(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
registry.add("deploy", {"name": "Deploy", "type_key": "deploy"})
@@ -9085,14 +9080,14 @@ class TestStepRegistryCustom:
assert not registry.is_installed("deploy")
def test_remove_missing_returns_false(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
removed = registry.remove("nonexistent")
assert removed is False
def test_list(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
registry.add("step-a", {"name": "A", "type_key": "step-a"})
@@ -9103,7 +9098,7 @@ class TestStepRegistryCustom:
assert "step-b" in installed
def test_is_installed(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
assert not registry.is_installed("missing")
@@ -9112,7 +9107,7 @@ class TestStepRegistryCustom:
assert registry.is_installed("exists")
def test_persistence(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry1 = StepRegistry(project_dir)
registry1.add("deploy", {"name": "Deploy", "type_key": "deploy"})
@@ -9121,7 +9116,7 @@ class TestStepRegistryCustom:
assert registry2.is_installed("deploy")
def test_corrupted_registry_resets(self, project_dir):
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
registry = StepRegistry(project_dir)
registry.steps_dir.mkdir(parents=True, exist_ok=True)
@@ -9133,7 +9128,7 @@ class TestStepRegistryCustom:
def test_registry_missing_steps_key_resets(self, project_dir):
"""Valid JSON but missing 'steps' key should not crash add/get."""
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
import json as _json
registry = StepRegistry(project_dir)
@@ -9153,7 +9148,7 @@ class TestStepRegistryCustom:
@pytest.mark.skipif(sys.platform == "win32", reason="chmod not reliable on Windows")
def test_registry_unreadable_file_resets(self, project_dir):
"""OSError reading the registry file should fall back to default."""
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
import json as _json
registry = StepRegistry(project_dir)
@@ -9178,7 +9173,7 @@ class TestStepRegistryCustom:
@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
def test_registry_load_refuses_symlinked_steps_dir(self, project_dir):
"""A symlinked steps directory must not be read from (defense-in-depth)."""
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.step.catalog import StepRegistry
import json as _json
outside = project_dir.parent / "outside-steps"
@@ -9196,7 +9191,7 @@ class TestStepRegistryCustom:
@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
def test_registry_save_refuses_symlinked_steps_dir(self, project_dir):
"""save() must refuse symlinked registry paths (defense-in-depth)."""
- from specify_cli.workflows.catalog import StepRegistry, StepValidationError
+ from specify_cli.workflows.step.catalog import StepRegistry, StepValidationError
outside = project_dir.parent / "outside-steps-save"
outside.mkdir(parents=True, exist_ok=True)
@@ -9222,7 +9217,7 @@ class TestStepCatalog:
def test_falsy_non_mapping_config_rejected(self, project_dir, body):
"""A FALSY non-mapping top level had the same ``or {}`` coercion, which
bypassed the isinstance guard. It must raise like a truthy non-mapping."""
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(body, encoding="utf-8")
@@ -9236,7 +9231,7 @@ class TestStepCatalog:
def test_falsy_non_list_catalogs_rejected(self, project_dir, body):
"""...and the same nested guard: a FALSY non-list ``catalogs:`` value must
raise rather than being swallowed as "no catalogs"."""
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(body, encoding="utf-8")
@@ -9252,7 +9247,7 @@ class TestStepCatalog:
"""An empty document, explicit null, or absent/empty ``catalogs:`` stays a
valid no-op — the layer contributes nothing and resolution falls
through."""
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(body, encoding="utf-8")
@@ -9260,7 +9255,7 @@ class TestStepCatalog:
assert catalog._load_catalog_config(config_path) is None
def test_default_catalogs(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
monkeypatch.setattr(Path, "home", lambda: project_dir)
monkeypatch.delenv("SPECKIT_STEP_CATALOG_URL", raising=False)
@@ -9271,7 +9266,7 @@ class TestStepCatalog:
assert entries[1].name == "community"
def test_env_var_override(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
monkeypatch.setenv("SPECKIT_STEP_CATALOG_URL", "https://example.com/step-catalog.json")
catalog = StepCatalog(project_dir)
@@ -9281,7 +9276,7 @@ class TestStepCatalog:
assert entries[0].url == "https://example.com/step-catalog.json"
def test_project_level_config(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(yaml.dump({
@@ -9302,7 +9297,7 @@ class TestStepCatalog:
def test_config_priority_bool_or_inf_rejected(self, project_dir, bad_priority):
"""`priority: true`/`.inf` in a step-catalog config raise a clean
validation error instead of coercing to 1 / crashing with OverflowError."""
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(yaml.dump({
@@ -9318,14 +9313,14 @@ class TestStepCatalog:
catalog.get_active_catalogs()
def test_validate_url_http_rejected(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
catalog = StepCatalog(project_dir)
with pytest.raises(StepValidationError, match="HTTPS"):
catalog._validate_catalog_url("http://evil.com/step-catalog.json")
def test_validate_url_localhost_http_allowed(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
# Should not raise
@@ -9344,7 +9339,7 @@ class TestStepCatalog:
ValueError past the command handler (which only catches
StepValidationError). Mirrors specify_cli.catalogs (#3435).
"""
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
catalog = StepCatalog(project_dir)
with pytest.raises(StepValidationError, match="malformed"):
@@ -9364,7 +9359,7 @@ class TestStepCatalog:
``entry.url`` is valid so validation only trips on the redirect target.
Mirrors specify_cli.catalogs (#3435).
"""
- from specify_cli.workflows.catalog import (
+ from specify_cli.workflows.step.catalog import (
StepCatalog,
StepCatalogEntry,
StepCatalogError,
@@ -9408,7 +9403,7 @@ class TestStepCatalog:
INTERMEDIATE hop — closing the https -> http -> attacker-https chain a
terminal-URL-only check would miss. Mirrors presets/extensions
(#3523 / #3524)."""
- from specify_cli.workflows.catalog import (
+ from specify_cli.workflows.step.catalog import (
StepCatalog,
StepCatalogEntry,
StepCatalogError,
@@ -9442,8 +9437,8 @@ class TestStepCatalog:
self, project_dir, monkeypatch
):
from specify_cli.authentication import http as auth_http
- from specify_cli.workflows import catalog as catalog_module
- from specify_cli.workflows.catalog import (
+ from specify_cli.workflows.step import catalog as catalog_module
+ from specify_cli.workflows.step.catalog import (
StepCatalog,
StepCatalogEntry,
StepCatalogError,
@@ -9495,7 +9490,7 @@ class TestStepCatalog:
assert not catalog.cache_dir.exists()
def test_add_catalog(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
catalog.add_catalog("https://example.com/new-steps.json", "my-steps")
@@ -9510,7 +9505,7 @@ class TestStepCatalog:
"""Step-catalog add_catalog() must not crash when an existing entry has a
`priority: .inf` (int(float('inf')) is an OverflowError) — _coerce_priority
treats it as 0 and the add succeeds."""
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.parent.mkdir(parents=True, exist_ok=True)
@@ -9532,7 +9527,7 @@ class TestStepCatalog:
def test_add_catalog_empty_yaml_file(self, project_dir):
"""An empty YAML config file should be treated as empty, not corrupted."""
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text("", encoding="utf-8")
@@ -9549,7 +9544,7 @@ class TestStepCatalog:
def test_add_catalog_rejects_falsy_non_mapping_config(
self, project_dir, bad
):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
config_path = project_dir / ".specify" / "step-catalogs.yml"
original = yaml.safe_dump(bad)
@@ -9563,7 +9558,7 @@ class TestStepCatalog:
assert config_path.read_text(encoding="utf-8") == original
def test_add_catalog_duplicate_rejected(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
catalog = StepCatalog(project_dir)
catalog.add_catalog("https://example.com/steps.json")
@@ -9572,7 +9567,7 @@ class TestStepCatalog:
catalog.add_catalog("https://example.com/steps.json")
def test_remove_catalog(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
catalog.add_catalog("https://example.com/s1.json", "first")
@@ -9586,7 +9581,7 @@ class TestStepCatalog:
assert len(data["catalogs"]) == 1
def test_remove_catalog_invalid_index(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
catalog = StepCatalog(project_dir)
catalog.add_catalog("https://example.com/s1.json")
@@ -9598,7 +9593,7 @@ class TestStepCatalog:
def test_remove_catalog_rejects_falsy_non_mapping_config(
self, project_dir, bad
):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
config_path = project_dir / ".specify" / "step-catalogs.yml"
config_path.write_text(yaml.safe_dump(bad), encoding="utf-8")
@@ -9607,14 +9602,14 @@ class TestStepCatalog:
StepCatalog(project_dir).remove_catalog(0)
def test_remove_catalog_no_config(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
catalog = StepCatalog(project_dir)
with pytest.raises(StepValidationError, match="No step catalog config file found"):
catalog.remove_catalog(0)
def test_add_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
import builtins
catalog = StepCatalog(project_dir)
@@ -9631,7 +9626,7 @@ class TestStepCatalog:
catalog.add_catalog("https://example.com/new-steps.json", "my-steps")
def test_remove_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+ from specify_cli.workflows.step.catalog import StepCatalog, StepValidationError
import builtins
catalog = StepCatalog(project_dir)
@@ -9649,7 +9644,7 @@ class TestStepCatalog:
catalog.remove_catalog(0)
def test_get_catalog_configs(self, project_dir):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
configs = catalog.get_catalog_configs()
@@ -9658,7 +9653,7 @@ class TestStepCatalog:
assert isinstance(configs[0]["install_allowed"], bool)
def test_search_with_mock_catalog(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
mock_data = {
"schema_version": "1.0",
@@ -9693,7 +9688,7 @@ class TestStepCatalog:
def test_search_with_non_string_fields(self, project_dir, monkeypatch):
"""Non-string catalog fields (e.g. integer id) must not raise TypeError."""
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
@@ -9717,7 +9712,7 @@ class TestStepCatalog:
def test_get_merged_steps_normalizes_list_ids_to_strings(self, project_dir, monkeypatch):
"""List-based catalog entries with non-string ids must be normalized."""
- from specify_cli.workflows.catalog import StepCatalog, StepCatalogEntry
+ from specify_cli.workflows.step.catalog import StepCatalog, StepCatalogEntry
catalog = StepCatalog(project_dir)
entry = StepCatalogEntry(
@@ -9742,7 +9737,7 @@ class TestStepCatalog:
def test_get_step_info_returns_entry_or_none(self, project_dir, monkeypatch):
"""get_step_info returns matching entry or None for missing ids."""
- from specify_cli.workflows.catalog import StepCatalog
+ from specify_cli.workflows.step.catalog import StepCatalog
catalog = StepCatalog(project_dir)
monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
@@ -9975,8008 +9970,582 @@ class PkgStep(StepBase):
# ===== CLI Step Remove Tests =====
-class TestWorkflowStepRemoveCLI:
- """Test the 'specify workflow step remove' CLI command edge cases."""
-
- def test_remove_orphaned_directory(self, project_dir, monkeypatch):
- """step remove works when directory exists but registry entry is missing.
-
- This covers the case where the registry was reset due to corruption.
- """
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
-
- # Create an orphaned step directory (no registry entry)
- step_dir = project_dir / ".specify" / "workflows" / "steps" / "orphan-step"
- step_dir.mkdir(parents=True)
- (step_dir / "step.yml").write_text(
- "step:\n type_key: orphan-step\n", encoding="utf-8"
- )
- (step_dir / "__init__.py").write_text("", encoding="utf-8")
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "remove", "orphan-step"])
- assert result.exit_code == 0, result.output
- assert not step_dir.exists()
- # Warning should be printed about missing registry entry
- assert "Warning" in result.output or "warning" in result.output.lower()
- def test_remove_not_installed(self, project_dir, monkeypatch):
- """step remove fails cleanly when neither directory nor registry entry exist."""
- from typer.testing import CliRunner
- from specify_cli import app
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "remove", "ghost-step"])
- assert result.exit_code != 0
- assert "not installed" in result.output
- def test_remove_registered_step(self, project_dir, monkeypatch):
- """step remove works normally when both directory and registry entry exist."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepRegistry
-
- monkeypatch.chdir(project_dir)
-
- # Set up a registered step with a directory
- registry = StepRegistry(project_dir)
- registry.add("my-step", {"name": "My Step", "type_key": "my-step", "version": "1.0.0"})
- step_dir = project_dir / ".specify" / "workflows" / "steps" / "my-step"
- step_dir.mkdir(parents=True)
- (step_dir / "step.yml").write_text(
- "step:\n type_key: my-step\n", encoding="utf-8"
- )
- (step_dir / "__init__.py").write_text("", encoding="utf-8")
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "remove", "my-step"])
- assert result.exit_code == 0, result.output
- assert not step_dir.exists()
- registry2 = StepRegistry(project_dir)
- assert not registry2.is_installed("my-step")
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_remove_rejects_symlinked_steps_base_dir(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- monkeypatch.chdir(project_dir)
- outside = project_dir.parent / "outside-steps"
- outside.mkdir(parents=True, exist_ok=True)
- steps_link = project_dir / ".specify" / "workflows" / "steps"
- steps_link.symlink_to(outside, target_is_directory=True)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "remove", "my-step"])
- assert result.exit_code != 0
- assert "Refusing to use symlinked step directory" in result.output
-class TestWorkflowRemoveGuard:
- def test_remove_rejects_traversal_registry_key(self, project_dir, monkeypatch):
- """A corrupted registry key must not let remove delete outside workflows/."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
- registry = WorkflowRegistry(project_dir)
- registry.add("../outside", {"name": "Bad"})
- outside = project_dir / ".specify" / "outside"
- outside.mkdir()
- sentinel = outside / "keep.txt"
- sentinel.write_text("keep", encoding="utf-8")
+class TestResumeWithInputs:
+ """Test that `workflow resume` can accept updated workflow inputs."""
- monkeypatch.chdir(project_dir)
- result = CliRunner().invoke(app, ["workflow", "remove", "../outside"])
+ _WF_CMD = """
+schema_version: "1.0"
+workflow:
+ id: "resume-cmd-wf"
+ name: "Resume Cmd WF"
+ version: "1.0.0"
+inputs:
+ cmd:
+ type: string
+ default: "exit 1"
+steps:
+ - id: s
+ type: shell
+ run: "{{ inputs.cmd }}"
+"""
- assert result.exit_code != 0
- assert "Invalid workflow ID" in result.output
- assert sentinel.read_text(encoding="utf-8") == "keep"
+ _WF_NUM = """
+schema_version: "1.0"
+workflow:
+ id: "resume-num-wf"
+ name: "Resume Num WF"
+ version: "1.0.0"
+inputs:
+ count:
+ type: number
+ default: 1
+steps:
+ - id: gate
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+"""
- @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])
- def test_remove_rejects_reserved_storage_ids(
- self, project_dir, monkeypatch, workflow_id
- ):
- """Reserved workflow storage directories must never be removable workflows."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
+ _WF_GATE_VERDICT = """
+schema_version: "1.0"
+workflow:
+ id: "resume-gate-verdict-wf"
+ name: "Resume Gate Verdict WF"
+ version: "1.0.0"
+inputs:
+ spec_verdict:
+ type: string
+ default: ""
+steps:
+ - id: gate
+ type: gate
+ message: "Review"
+ options: [approve, reject]
+ on_reject: retry
+ verdict_input: spec_verdict
+"""
- registry = WorkflowRegistry(project_dir)
- registry.add(workflow_id, {"name": "Bad"})
- reserved_dir = project_dir / ".specify" / "workflows" / workflow_id
- reserved_dir.mkdir(exist_ok=True)
- sentinel = reserved_dir / "keep.txt"
- sentinel.write_text("keep", encoding="utf-8")
+ _WF_RUNTIME_CONFIG = """
+schema_version: "1.0"
+workflow:
+ id: "resume-runtime-config-wf"
+ name: "Resume Runtime Config WF"
+ version: "1.0.0"
+inputs:
+ config:
+ type: string
+ default: "./initial-agent.yaml"
+ agent_name:
+ type: string
+ default: "initial-root"
+ model_name:
+ type: string
+ default: "initial/model"
+steps:
+ - id: implement
+ type: command
+ command: speckit.implement
+ integration: docker-agent
+ integration_args:
+ - "{{ inputs.config }}"
+ integration_options:
+ agent: "{{ inputs.agent_name }}"
+ safety: balanced
+ model: "{{ inputs.model_name }}"
+"""
- monkeypatch.chdir(project_dir)
- result = CliRunner().invoke(app, ["workflow", "remove", workflow_id])
+ _WF_DYNAMIC_INTEGRATION = """
+schema_version: "1.0"
+workflow:
+ id: "resume-dynamic-integration-wf"
+ name: "Resume Dynamic Integration WF"
+ version: "1.0.0"
+inputs:
+ integration:
+ type: string
+ default: docker-agent
+ config:
+ type: string
+ default: "./initial-agent.yaml"
+steps:
+ - id: implement
+ type: command
+ command: speckit.implement
+ integration: "{{ inputs.integration }}"
+ integration_args:
+ - "{{ inputs.config }}"
+"""
- assert result.exit_code != 0
- assert "Invalid workflow ID" in result.output
- assert sentinel.read_text(encoding="utf-8") == "keep"
+ def _engine(self, project_dir):
+ from specify_cli.workflows.engine import WorkflowEngine
+ return WorkflowEngine(project_dir)
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_remove_refuses_symlinked_workflow_dir(self, project_dir, monkeypatch):
- """A symlinked workflow directory must not let remove delete its target."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
+ def test_resume_with_input_reruns_step_with_new_value(self, project_dir):
+ from specify_cli.workflows.engine import WorkflowDefinition
+ from specify_cli.workflows.base import RunStatus
- registry = WorkflowRegistry(project_dir)
- registry.add("test-wf", {"name": "Test"})
- outside = project_dir / "outside-workflow-remove-target"
- outside.mkdir(exist_ok=True)
- sentinel = outside / "keep.txt"
- sentinel.write_text("keep", encoding="utf-8")
- (project_dir / ".specify" / "workflows" / "test-wf").symlink_to(
- outside, target_is_directory=True
- )
+ definition = WorkflowDefinition.from_string(self._WF_CMD)
+ engine = self._engine(project_dir)
- monkeypatch.chdir(project_dir)
- result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+ state = engine.execute(definition)
+ assert state.status == RunStatus.FAILED # "exit 1" fails
- assert result.exit_code != 0
- assert "symlinked .specify/workflows/test-wf" in result.output
- assert sentinel.read_text(encoding="utf-8") == "keep"
- assert WorkflowRegistry(project_dir).is_installed("test-wf")
+ resumed = engine.resume(state.run_id, {"cmd": "exit 0"})
+ assert resumed.status == RunStatus.COMPLETED
+ assert resumed.inputs["cmd"] == "exit 0"
- def test_remove_refuses_non_directory_workflow_path(self, project_dir, monkeypatch):
- """A file at the workflow path must fail cleanly instead of crashing."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
+ def test_resume_without_input_preserves_inputs(self, project_dir):
+ from specify_cli.workflows.engine import WorkflowDefinition
+ from specify_cli.workflows.base import RunStatus
- registry = WorkflowRegistry(project_dir)
- registry.add("test-wf", {"name": "Test"})
- workflow_path = project_dir / ".specify" / "workflows" / "test-wf"
- workflow_path.write_text("not a directory", encoding="utf-8")
+ definition = WorkflowDefinition.from_string(self._WF_CMD)
+ engine = self._engine(project_dir)
- monkeypatch.chdir(project_dir)
- result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
+ state = engine.execute(definition)
+ assert state.status == RunStatus.FAILED
- assert result.exit_code != 0
- assert "exists but is not a directory" in result.output
- assert workflow_path.read_text(encoding="utf-8") == "not a directory"
- assert WorkflowRegistry(project_dir).is_installed("test-wf")
+ resumed = engine.resume(state.run_id)
+ assert resumed.status == RunStatus.FAILED # still "exit 1"
+ assert resumed.inputs["cmd"] == "exit 1"
- @pytest.mark.parametrize("error_type", [OSError, TypeError, ValueError])
- def test_remove_registry_save_failure_preserves_files_and_registry(
- self, project_dir, monkeypatch, error_type
+ def test_resume_re_resolves_complete_integration_config(
+ self, project_dir, monkeypatch
):
- """If persisting the registry removal fails, the workflow's files must
- not have already been deleted: the CLI must not delete files before the
- registry successfully records the removal, and it must fail cleanly."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
- workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
- workflow_dir.mkdir(parents=True, exist_ok=True)
- (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
+ from specify_cli.workflows.base import RunStatus
+ from specify_cli.workflows.engine import WorkflowDefinition
- def boom(self):
- raise error_type("save failed")
+ calls = []
+ return_codes = iter((1, 0))
- monkeypatch.chdir(project_dir)
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", boom)
- result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- # Files must survive a registry-save failure.
- assert (workflow_dir / "workflow.yml").read_text(encoding="utf-8") == "keep-me"
- # The on-disk registry must still claim the workflow installed.
- assert WorkflowRegistry(project_dir).is_installed("test-wf")
- # The directory must be restored to its exact original location, with
- # no leftover staging directory from the stage/restore-on-failure
- # sequence.
- entries = [
- p.name
- for p in (project_dir / ".specify" / "workflows").iterdir()
- if p.name != "workflow-registry.json"
- ]
- assert entries == ["test-wf"]
+ def fake_run(args, **kwargs):
+ calls.append(args)
+ return type("Result", (), {"returncode": next(return_codes)})()
- def test_remove_staged_cleanup_failure_reports_warning_not_error(
- self, project_dir, monkeypatch
- ):
- """The directory is staged (atomically renamed out of
- .specify/workflows/<id>) *before* the registry write, and the actual
- deletion of the staged directory only happens *after* the registry
- has already durably recorded the removal. If that final deletion
- fails, the registry write already succeeded and must stand -- an
- "Error: Failed to remove..." message at that point would contradict
- the registry, which is exactly the incoherent state this staging
- order exists to prevent. It must be reported as a cleanup warning,
- and the command must still succeed."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
+ monkeypatch.delenv(
+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
+ )
+ monkeypatch.setattr(
+ "shutil.which",
+ lambda name: (
+ "/usr/bin/docker-agent"
+ if name in {"docker-agent", "/usr/bin/docker-agent"}
+ else None
+ ),
+ )
+ monkeypatch.setattr("subprocess.run", fake_run)
- registry = WorkflowRegistry(project_dir)
- registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
- workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
- workflow_dir.mkdir(parents=True, exist_ok=True)
- (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
+ definition = WorkflowDefinition.from_string(self._WF_RUNTIME_CONFIG)
+ engine = self._engine(project_dir)
+ state = engine.execute(definition)
- def boom(*args, **kwargs):
- raise OSError("permission denied")
-
- monkeypatch.chdir(project_dir)
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr("shutil.rmtree", boom)
- result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
-
- assert result.exit_code == 0
- assert "Warning" in result.output
- # The registry write already committed -- it must stand.
- assert not WorkflowRegistry(project_dir).is_installed("test-wf")
- # The original install path is gone (staged away before the registry
- # write ever ran); only a leftover staged directory remains, never
- # at the original path the registry/CLI would treat as installed.
- assert not workflow_dir.exists()
- leftovers = [
- p
- for p in (project_dir / ".specify" / "workflows").iterdir()
- if p.name != "workflow-registry.json"
+ assert state.status is RunStatus.FAILED
+ assert state.step_results["implement"]["integration_args"] == [
+ "./initial-agent.yaml"
]
- assert len(leftovers) == 1
- assert (leftovers[0] / "workflow.yml").read_text(encoding="utf-8") == "keep-me"
-
- def test_remove_stage_restore_failure_escapes_rich_markup(
- self, temp_dir, monkeypatch
- ):
- """When the registry write fails (already rolled back in-memory by
- WorkflowRegistry.remove()) and the attempt to rename the staged
- directory back to its original location also fails, both the
- restore exception and the registry-update exception interpolated
- into these warning/error messages must be escaped like every other
- error path here."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- project_dir = temp_dir / "weird[project]"
- project_dir.mkdir()
- (project_dir / ".specify").mkdir()
- (project_dir / ".specify" / "workflows").mkdir()
+ assert state.step_results["implement"]["integration_options"] == {
+ "agent": "initial-root",
+ "safety": "balanced",
+ }
- registry = WorkflowRegistry(project_dir)
- registry.add("test-wf", {"name": "Test", "version": "1.0.0"})
- workflow_dir = project_dir / ".specify" / "workflows" / "test-wf"
- workflow_dir.mkdir(parents=True, exist_ok=True)
- (workflow_dir / "workflow.yml").write_text("keep-me", encoding="utf-8")
-
- def save_boom(self):
- raise OSError("[reg] disk full")
-
- real_rename = os.rename
- rename_calls = {"n": 0}
-
- def rename_boom(src, dst):
- rename_calls["n"] += 1
- if rename_calls["n"] == 1:
- # Allow the initial stage-out rename to succeed so the
- # restore-back rename (the second call) is what fails.
- return real_rename(src, dst)
- raise OSError("[stage] permission denied")
-
- monkeypatch.chdir(project_dir)
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", save_boom)
- mp.setattr(os, "rename", rename_boom)
- result = CliRunner().invoke(app, ["workflow", "remove", "test-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- output_compact = "".join(result.output.split())
- assert "[stage]permissiondenied" in output_compact
- assert "[reg]diskfull" in output_compact
-
-
-class TestWorkflowAddCaseInsensitiveSuffix:
- """`workflow add` must detect a local YAML file case-insensitively, matching
- `workflow run` (_commands.py:workflow_run) and the engine loader
- (engine.py:WorkflowEngine.load_workflow), which both use `.suffix.lower()`.
- Without it, `workflow run Sample.YAML` works but `workflow add Sample.YAML`
- fails — an add/run inconsistency for an uppercase extension."""
-
- def test_plain_path_accepts_uppercase_extension(self, temp_dir, monkeypatch, sample_workflow_yaml):
- from typer.testing import CliRunner
- from specify_cli import app
-
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- src = temp_dir / "Sample.YAML"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- # Before the fix: `.suffix in (...)` is case-sensitive, so ".YAML" is not
- # recognized as a local file; the path falls through to catalog lookup
- # and fails. After the fix it installs like the lowercase happy path.
- assert result.exit_code == 0, result.output
- assert "installed" in result.output
-
- def test_dev_path_accepts_uppercase_extension(self, temp_dir, monkeypatch, sample_workflow_yaml):
- from typer.testing import CliRunner
- from specify_cli import app
-
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- src = temp_dir / "Sample.YAML"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", "--dev", str(src)])
-
- # Before the fix the --dev branch rejects ".YAML" with
- # "--dev source must be a workflow YAML file ...".
- assert result.exit_code == 0, result.output
- assert "installed" in result.output
-
- def test_lowercase_extension_still_installs(self, temp_dir, monkeypatch, sample_workflow_yaml):
- """Happy path (lowercase .yml) is unchanged by the case-normalization."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- src = temp_dir / "sample.yml"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- assert result.exit_code == 0, result.output
- assert "installed" in result.output
-
- def test_add_installs_workflow_with_custom_step(self, temp_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- step_dir = temp_dir / ".specify" / "workflows" / "steps" / "test-add-step"
- step_dir.mkdir(parents=True)
- step_manifest = {
- "schema_version": "1.0",
- "step": {
- "type_key": "test-add-step",
- "name": "Test Add Step",
- "version": "1.0.0",
+ resumed = engine.resume(
+ state.run_id,
+ {
+ "config": "./changed-on-resume.yaml",
+ "agent_name": "changed-root",
+ "model_name": "changed/model",
},
- }
- (step_dir / "step.yml").write_text(
- yaml.safe_dump(step_manifest, sort_keys=False),
- encoding="utf-8",
)
- (step_dir / "__init__.py").write_text(
- """
-from specify_cli.workflows.base import StepBase, StepResult
+ assert resumed.status is RunStatus.COMPLETED
+ assert resumed.inputs["config"] == "./changed-on-resume.yaml"
+ assert len(calls) == 2
+ assert "./initial-agent.yaml" in calls[0]
+ assert "./changed-on-resume.yaml" in calls[1]
+ assert "./initial-agent.yaml" not in calls[1]
+ assert calls[1][calls[1].index("--agent") + 1] == "changed-root"
+ assert calls[1][calls[1].index("--model") + 1] == "changed/model"
-class TestAddStep(StepBase):
- type_key = "test-add-step"
+ def test_resume_does_not_mix_new_integration_with_old_runtime_config(
+ self, project_dir, monkeypatch
+ ):
+ from specify_cli.workflows.base import RunStatus
+ from specify_cli.workflows.engine import WorkflowDefinition
- def execute(self, config, context):
- return StepResult()
-""",
- encoding="utf-8",
+ monkeypatch.delenv(
+ "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
)
-
- src = temp_dir / "sample.yml"
- workflow_definition = {
- "schema_version": "1.0",
- "workflow": {
- "id": "test-workflow-with-custom-step",
- "name": "Test Workflow With Custom Step",
- "version": "1.0.0",
- },
- "steps": [
- {"id": "custom-step", "type": "test-add-step"},
- ],
- }
- src.write_text(
- yaml.safe_dump(workflow_definition, sort_keys=False),
- encoding="utf-8",
+ monkeypatch.setattr(
+ "shutil.which",
+ lambda name: (
+ "/usr/bin/docker-agent"
+ if name in {"docker-agent", "/usr/bin/docker-agent"}
+ else None
+ ),
)
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- assert result.exit_code == 0, result.output
- installed_workflow = (
- temp_dir
- / ".specify"
- / "workflows"
- / "test-workflow-with-custom-step"
- / "workflow.yml"
+ monkeypatch.setattr(
+ "subprocess.run",
+ lambda *args, **kwargs: type("Result", (), {"returncode": 1})(),
)
- assert installed_workflow.is_file()
+ definition = WorkflowDefinition.from_string(self._WF_DYNAMIC_INTEGRATION)
+ engine = self._engine(project_dir)
+ state = engine.execute(definition)
+ assert state.status is RunStatus.FAILED
+
+ resumed = engine.resume(
+ state.run_id,
+ {"integration": "claude", "config": "./changed-on-resume.yaml"},
+ )
-class TestWorkflowInfoStepGraph:
- """`workflow info` must render each step as `→ <id> [<type>]` with LITERAL
- brackets. Rich parses an unescaped `[<type>]` as a style tag and silently
- swallows it, so the step type would vanish from the output."""
+ assert resumed.status is RunStatus.FAILED
+ step_result = resumed.step_results["implement"]
+ assert step_result["integration"] == "claude"
+ assert step_result["integration_args"] == ["./changed-on-resume.yaml"]
+ assert "Integration 'claude'" in (step_result["error"] or "")
+ assert "./initial-agent.yaml" not in str(step_result)
- def test_step_type_rendered_in_literal_brackets(self, temp_dir, monkeypatch):
- import types
+ def test_resume_merges_and_coerces_typed_input(self, project_dir):
+ import json as _json
+ from specify_cli.workflows.engine import WorkflowDefinition
+ from specify_cli.workflows.base import RunStatus
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowEngine
+ definition = WorkflowDefinition.from_string(self._WF_NUM)
+ engine = self._engine(project_dir)
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ state = engine.execute(definition)
+ assert state.status == RunStatus.PAUSED
- fake = types.SimpleNamespace(
- name="My WF", id="my-wf", version="1.0.0", author="", description="",
- default_integration=None, inputs={},
- steps=[{"id": "step-one", "type": "gate"}],
- )
- monkeypatch.setattr(WorkflowEngine, "load_workflow", lambda self, wid: fake)
- monkeypatch.chdir(temp_dir)
-
- result = CliRunner().invoke(app, ["workflow", "info", "my-wf"])
-
- assert result.exit_code == 0, result.output
- assert "step-one" in result.output
- # The step type must survive as a literal bracketed token, not be eaten
- # by Rich as an unknown style tag.
- assert "[gate]" in result.output
-
- def test_definition_metadata_fields_escaped(self, temp_dir, monkeypatch):
- """Every metadata field printed from the workflow definition (name,
- description, author, integration, input name/type) is untrusted
- workflow.yml content. An unescaped `[...]` in any of them would be
- parsed as a Rich style tag and silently swallowed, so bracketed text
- must survive literally in the output."""
- import types
-
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowEngine
+ resumed = engine.resume(state.run_id, {"count": "5"})
+ assert resumed.inputs["count"] == 5 # coerced string -> number
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
-
- fake = types.SimpleNamespace(
- name="My [WF]",
- id="my-wf",
- version="1.0.0 [beta]",
- author="Jane [Doe]",
- description="Does [stuff] nicely",
- default_integration="claude [code]",
- inputs={"in [put]": {"type": "str [ing]", "required": True}},
- steps=[],
+ inputs_file = (
+ project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
)
- monkeypatch.setattr(WorkflowEngine, "load_workflow", lambda self, wid: fake)
- monkeypatch.chdir(temp_dir)
-
- result = CliRunner().invoke(app, ["workflow", "info", "my-wf"])
-
- assert result.exit_code == 0, result.output
- # Each bracketed token must render literally rather than be consumed as
- # an unknown Rich style tag.
- assert "My [WF]" in result.output
- assert "1.0.0 [beta]" in result.output
- assert "Jane [Doe]" in result.output
- assert "Does [stuff] nicely" in result.output
- assert "claude [code]" in result.output
- assert "in [put]" in result.output
- assert "str [ing]" in result.output
-
- def test_catalog_metadata_fields_escaped(self, temp_dir, monkeypatch):
- """When the workflow is only found in the catalog (not on disk), its
- catalog-derived fields (name, description, tags) are untrusted too and
- must be escaped so bracketed content renders literally."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowEngine
- from specify_cli.workflows import catalog as catalog_mod
+ assert _json.loads(inputs_file.read_text())["inputs"]["count"] == 5
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ def test_resume_invalid_typed_input_raises(self, project_dir):
+ from specify_cli.workflows.engine import WorkflowDefinition
- def _not_on_disk(self, wid):
- raise FileNotFoundError(wid)
+ definition = WorkflowDefinition.from_string(self._WF_NUM)
+ engine = self._engine(project_dir)
- monkeypatch.setattr(WorkflowEngine, "load_workflow", _not_on_disk)
- monkeypatch.setattr(
- catalog_mod.WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "name": "Cat [WF]",
- "version": "2.0.0 [rc]",
- "description": "From [catalog]",
- "tags": ["a [b]", "c [d]"],
- },
- )
- monkeypatch.chdir(temp_dir)
-
- result = CliRunner().invoke(app, ["workflow", "info", "cat-wf"])
-
- assert result.exit_code == 0, result.output
- assert "Cat [WF]" in result.output
- assert "2.0.0 [rc]" in result.output
- assert "From [catalog]" in result.output
- assert "a [b]" in result.output
- assert "c [d]" in result.output
-
- def test_not_found_id_escaped(self, temp_dir, monkeypatch):
- """When the workflow is neither on disk nor in the catalog, the
- not-found error echoes the requested ID. That ID is user input, so a
- bracketed value must render literally instead of being parsed (and
- swallowed) as a Rich style tag."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowEngine
- from specify_cli.workflows import catalog as catalog_mod
+ state = engine.execute(definition)
+ with pytest.raises(ValueError):
+ engine.resume(state.run_id, {"count": "not-a-number"})
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
+ def test_resume_rejects_legacy_invalid_options_before_state_mutation(
+ self, project_dir, monkeypatch
+ ):
+ from specify_cli.workflows.base import RunStatus
+ from specify_cli.workflows.engine import RunState, WorkflowDefinition
- def _not_on_disk(self, wid):
- raise FileNotFoundError(wid)
+ definition = WorkflowDefinition.from_string(self._WF_NUM)
+ engine = self._engine(project_dir)
+ state = engine.execute(definition)
+ assert state.status == RunStatus.PAUSED
- monkeypatch.setattr(WorkflowEngine, "load_workflow", _not_on_disk)
- monkeypatch.setattr(
- catalog_mod.WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: None,
+ workflow_copy = (
+ project_dir
+ / ".specify"
+ / "workflows"
+ / "runs"
+ / state.run_id
+ / "workflow.yml"
+ )
+ workflow_copy.write_text(
+ self._WF_NUM.replace(
+ 'version: "1.0.0"', 'version: "1.0.0"\n options: [max_tokens]'
+ ),
+ encoding="utf-8",
)
- monkeypatch.chdir(temp_dir)
-
- result = CliRunner().invoke(app, ["workflow", "info", "ghost [wf]"])
- assert result.exit_code == 1, result.output
- assert "not found" in result.output
- # The bracketed ID must survive literally, not be eaten as markup.
- assert "ghost [wf]" in result.output
+ def fail_step_context(*args, **kwargs):
+ raise AssertionError("StepContext must not be created")
+ monkeypatch.setattr("specify_cli.workflows.engine.StepContext", fail_step_context)
-class TestWorkflowAddSymlinkGuard:
- def test_add_malformed_ipv6_url_exits_cleanly(self, temp_dir, monkeypatch):
- """A malformed IPv6 URL must produce a clean error, not a ValueError traceback."""
- from typer.testing import CliRunner
- from specify_cli import app
+ with pytest.raises(ValueError, match="'workflow.options' must be a mapping or null"):
+ engine.resume(state.run_id, {"count": "5"})
- (temp_dir / ".specify").mkdir(exist_ok=True)
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(
- app,
- ["workflow", "add", "https://[::1/wf.yaml"],
- catch_exceptions=True,
- )
+ reloaded = RunState.load(state.run_id, project_dir)
+ assert reloaded.status == RunStatus.PAUSED
+ assert reloaded.error is None
+ assert reloaded.inputs["count"] == 1
- assert result.exit_code == 1
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Invalid URL" in result.output
+ def test_retry_verdict_input_is_consumed_and_can_be_replaced(self, project_dir):
+ import json as _json
+ from specify_cli.workflows.engine import WorkflowDefinition
+ from specify_cli.workflows.base import RunStatus
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_add_refuses_symlinked_specify(self, temp_dir, monkeypatch):
- """workflow add must refuse a symlinked .specify (writes could escape root)."""
- from typer.testing import CliRunner
- from specify_cli import app
+ definition = WorkflowDefinition.from_string(self._WF_GATE_VERDICT)
+ engine = self._engine(project_dir)
- outside = temp_dir.parent / "outside-specify-target"
- (outside / "workflows").mkdir(parents=True, exist_ok=True)
- (temp_dir / ".specify").symlink_to(outside, target_is_directory=True)
+ state = engine.execute(definition, {"spec_verdict": "reject"})
+ assert state.status == RunStatus.PAUSED
+ assert state.inputs["spec_verdict"] == ""
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", "anything.yml"])
+ inputs_file = (
+ project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
+ )
+ assert _json.loads(inputs_file.read_text())["inputs"]["spec_verdict"] == ""
- assert result.exit_code != 0
- assert "symlinked .specify" in result.output
+ paused_again = engine.resume(state.run_id)
+ assert paused_again.status == RunStatus.PAUSED
+ assert paused_again.inputs["spec_verdict"] == ""
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_add_refuses_symlinked_workflows_dir(self, temp_dir, monkeypatch):
- """workflow add must refuse a symlinked .specify/workflows directory."""
- from typer.testing import CliRunner
- from specify_cli import app
+ completed = engine.resume(state.run_id, {"spec_verdict": "approve"})
+ assert completed.status == RunStatus.COMPLETED
+ assert completed.step_results["gate"]["output"]["choice"] == "approve"
- (temp_dir / ".specify").mkdir()
- outside = temp_dir.parent / "outside-workflows-target"
- outside.mkdir(parents=True, exist_ok=True)
- (temp_dir / ".specify" / "workflows").symlink_to(outside, target_is_directory=True)
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", "anything.yml"])
- assert result.exit_code != 0
- assert "symlinked .specify/workflows" in result.output
- def test_add_escapes_rich_markup_in_validation_errors(self, temp_dir, monkeypatch):
- """User-controlled YAML values in validation errors must not be parsed as Rich markup."""
- from typer.testing import CliRunner
- from specify_cli import app
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- src = temp_dir / "incoming.yml"
- src.write_text(
- """
-schema_version: "1.0"
-workflow:
- id: "markup-wf"
- name: "Markup"
- version: "[bold]bad[/bold]"
-steps:
- - id: step-one
- command: speckit.specify
-""",
- encoding="utf-8",
- )
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
- assert result.exit_code != 0
- assert "[bold]bad[/bold]" in result.output
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_add_refuses_symlinked_id_dir(self, temp_dir, monkeypatch, sample_workflow_yaml):
- """A symlinked <id> install dir must not let a copy escape the project root."""
- from typer.testing import CliRunner
- from specify_cli import app
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- outside = temp_dir.parent / "outside-id-target"
- outside.mkdir(parents=True, exist_ok=True)
- # <id> from the YAML below is "test-workflow"; plant it as a symlink.
- (temp_dir / ".specify" / "workflows" / "test-workflow").symlink_to(
- outside, target_is_directory=True
- )
- src = temp_dir / "incoming.yml"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
- assert result.exit_code != 0
- # No write-through: the symlink target stays empty.
- assert not (outside / "workflow.yml").exists()
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_add_refuses_symlinked_workflow_yml_leaf(self, temp_dir, monkeypatch, sample_workflow_yaml):
- """A symlinked <id>/workflow.yml must not let copy2 write through the link."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- id_dir = temp_dir / ".specify" / "workflows" / "test-workflow"
- id_dir.mkdir(parents=True)
- outside_file = temp_dir.parent / "outside-leaf-target.yml"
- outside_file.write_text("original\n", encoding="utf-8")
- (id_dir / "workflow.yml").symlink_to(outside_file)
- src = temp_dir / "incoming.yml"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- assert result.exit_code != 0
- # Rich may wrap the message; assert on the unbroken path fragment.
- assert "test-workflow/workflow.yml" in result.output
- assert "symlinked" in result.output
- # The link target content is untouched.
- assert outside_file.read_text(encoding="utf-8") == "original\n"
-
- def test_add_refuses_non_directory_id(self, temp_dir, monkeypatch, sample_workflow_yaml):
- """An <id> path that already exists as a file must fail cleanly, not crash."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- wf_dir = temp_dir / ".specify" / "workflows"
- wf_dir.mkdir(parents=True)
- (wf_dir / "test-workflow").write_text("not a dir", encoding="utf-8")
- src = temp_dir / "incoming.yml"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- assert result.exit_code != 0
- assert "exists but is not a directory" in result.output
- assert result.exception is None or isinstance(result.exception, SystemExit)
-
- def test_add_refuses_workflow_yml_as_directory(self, temp_dir, monkeypatch, sample_workflow_yaml):
- """A pre-existing <id>/workflow.yml *directory* must fail cleanly, not crash."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- id_dir = temp_dir / ".specify" / "workflows" / "test-workflow"
- id_dir.mkdir(parents=True)
- # Plant workflow.yml as a directory so a later write/copy2 would raise
- # IsADirectoryError without the explicit non-file guard.
- (id_dir / "workflow.yml").mkdir()
- src = temp_dir / "incoming.yml"
- src.write_text(sample_workflow_yaml, encoding="utf-8")
-
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(src)])
-
- assert result.exit_code != 0
- assert "test-workflow/workflow.yml" in result.output
- assert "is not a file" in result.output
- # Clean exit, not an unhandled IsADirectoryError traceback.
- assert result.exception is None or isinstance(result.exception, SystemExit)
-
- def test_safe_workflow_id_dir_escapes_markup_in_invalid_id(self, temp_dir, capsys):
- """A traversal <id> carrying Rich markup must be escaped, not interpreted."""
- import typer
- from specify_cli.workflows._commands import _safe_workflow_id_dir
-
- workflows_dir = temp_dir / ".specify" / "workflows"
- workflows_dir.mkdir(parents=True)
- # Traversal (so the "Invalid workflow ID" branch fires) plus markup.
- with pytest.raises(typer.Exit):
- _safe_workflow_id_dir(workflows_dir, "../[red]evil[/red]")
+class TestWorkflowCliAlignment:
+ """CLI alignment with extension/preset commands (#2342)."""
- out = capsys.readouterr().out
- # Literal bracketed text survives; Rich did not consume it as a tag.
- assert "[red]evil[/red]" in out
-
- def test_add_rejects_reserved_overlay_storage_id(self, temp_dir, monkeypatch):
- """workflow add must not install into the overlay storage directory."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- overlay_file = temp_dir / "incoming.yml"
- overlay_file.write_text(
- """
-schema_version: "1.0"
-workflow:
- id: "overlays"
- name: "Bad Workflow"
- version: "1.0.0"
-steps:
- - id: step-one
- command: speckit.specify
-""".strip()
- + "\n",
- encoding="utf-8",
- )
+ def test_registry_add_rolls_back_memory_on_save_failure(self, project_dir, monkeypatch):
+ from specify_cli.workflows.catalog import WorkflowRegistry
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "add", str(overlay_file)])
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
- assert result.exit_code != 0
- assert "Invalid workflow ID" in result.output
- assert not (temp_dir / ".specify" / "workflows" / "overlays" / "workflow.yml").exists()
+ def boom():
+ raise OSError("disk full")
- @pytest.mark.parametrize(
- "workflow_id",
- [
- "overlays",
- "runs",
- "steps",
- "nested/workflow",
- "nested\\workflow",
- "bad id",
- " bad-id",
- "bad-id ",
- ],
- )
- def test_safe_workflow_id_dir_rejects_reserved_or_non_segment_ids(
- self, temp_dir, workflow_id, capsys
- ):
- """Install IDs must not collide with workflow internals or create nested paths."""
- import typer
- from specify_cli.workflows._commands import _safe_workflow_id_dir
+ monkeypatch.setattr(registry, "save", boom)
+ with pytest.raises(OSError):
+ registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
+ assert registry.get("align-wf")["version"] == "1.0.0"
- workflows_dir = temp_dir / ".specify" / "workflows"
- workflows_dir.mkdir(parents=True)
+ with pytest.raises(OSError):
+ registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
+ assert registry.get("other-wf") is None
- with pytest.raises(typer.Exit):
- _safe_workflow_id_dir(workflows_dir, workflow_id)
+ @pytest.mark.parametrize("error_type", [TypeError, ValueError])
+ def test_registry_add_rolls_back_memory_on_serialization_failure(
+ self, project_dir, monkeypatch, error_type
+ ):
+ from specify_cli.workflows.catalog import WorkflowRegistry
- assert "Invalid workflow ID" in capsys.readouterr().out
- assert not (workflows_dir / workflow_id).exists()
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_list_refuses_symlinked_runs_dir(self, temp_dir, monkeypatch):
- """workflow commands using the project shim must refuse symlinked run storage."""
- from typer.testing import CliRunner
- from specify_cli import app
+ def boom():
+ raise error_type("not JSON serializable")
- (temp_dir / ".specify" / "workflows").mkdir(parents=True)
- outside = temp_dir.parent / "outside-runs-target"
- outside.mkdir(parents=True, exist_ok=True)
- (temp_dir / ".specify" / "workflows" / "runs").symlink_to(
- outside, target_is_directory=True
- )
+ monkeypatch.setattr(registry, "save", boom)
+ with pytest.raises(error_type):
+ registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
+ assert registry.get("align-wf")["version"] == "1.0.0"
- monkeypatch.chdir(temp_dir)
- result = CliRunner().invoke(app, ["workflow", "list"])
+ with pytest.raises(error_type):
+ registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
+ assert registry.get("other-wf") is None
- assert result.exit_code != 0
- assert "symlinked .specify/workflows/runs" in result.output
+ def test_registry_add_survives_non_dict_existing_entry(self, project_dir):
+ from specify_cli.workflows.catalog import WorkflowRegistry
+ registry = WorkflowRegistry(project_dir)
+ registry.data["workflows"]["align-wf"] = "corrupted"
+ registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
+ assert registry.get("align-wf")["version"] == "1.0.0"
-class TestWorkflowStepRichMarkup:
- """Step discovery commands render metadata as literal text."""
+ def test_step_registry_add_survives_non_dict_existing_entry(self, project_dir):
+ """StepRegistry.add must treat a corrupted non-dict existing entry as
+ absent rather than crash on existing.get() (parity with
+ WorkflowRegistry.add)."""
+ from specify_cli.workflows.step.catalog import StepRegistry
- METADATA = {
- "id": "[magenta]step-id[/magenta]",
- "name": "[red]Step Name[/red]",
- "version": "[green]1.0.0[/green]",
- "author": "[yellow]Author[/yellow]",
- "description": "[blue]Description[/blue]",
- }
+ registry = StepRegistry(project_dir)
+ registry.data["steps"]["my-step"] = "corrupted"
+ registry.add("my-step", {"version": "1.0.0"})
+ assert registry.get("my-step")["version"] == "1.0.0"
- def test_search_escapes_catalog_metadata(
- self, project_dir, monkeypatch
+ @pytest.mark.parametrize(
+ "contents",
+ [
+ "not json",
+ "[]",
+ '{"schema_version": "1.0"}',
+ '{"schema_version": "1.0", "workflows": "broken"}',
+ ],
+ )
+ def test_registry_load_rejects_corrupt_contents(
+ self, project_dir, contents
):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
-
- metadata = dict(self.METADATA)
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- StepCatalog, "search", lambda _catalog, query=None: [metadata]
- )
-
- result = CliRunner().invoke(app, ["workflow", "step", "search"])
+ from specify_cli.workflows.catalog import WorkflowRegistry
- assert result.exit_code == 0, result.output
- assert metadata["name"] in result.output
- assert metadata["id"] in result.output
- assert metadata["version"] in result.output
- assert metadata["description"] in result.output
+ registry = WorkflowRegistry(project_dir)
+ registry.workflows_dir.mkdir(parents=True, exist_ok=True)
+ registry.registry_path.write_text(contents, encoding="utf-8")
- def test_info_escapes_catalog_metadata(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog, StepRegistry
+ with pytest.raises(OSError, match="corrupt"):
+ WorkflowRegistry(project_dir)
- metadata = dict(self.METADATA)
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(StepRegistry, "get", lambda _registry, step_id: None)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda _catalog, step_id: metadata,
- )
+ assert registry.registry_path.read_text(encoding="utf-8") == contents
- result = CliRunner().invoke(
- app, ["workflow", "step", "info", metadata["id"]]
- )
+ def test_registry_save_refuses_symlinked_parent(self, project_dir, tmp_path):
+ """Construction now fails closed on a symlinked .specify just like
+ an unreadable registry file: a symlinked parent must never be
+ silently tolerated up to save() -- it must raise immediately."""
+ from specify_cli.workflows.catalog import WorkflowRegistry
- assert result.exit_code == 0, result.output
- for value in metadata.values():
- assert value in result.output
+ outside = tmp_path / "outside-specify"
+ outside.mkdir()
+ specify_dir = project_dir / ".specify"
+ if specify_dir.exists():
+ shutil.rmtree(specify_dir)
+ specify_dir.symlink_to(outside)
+ with pytest.raises(OSError, match="symlink"):
+ WorkflowRegistry(project_dir)
+ assert not (outside / "workflows").exists()
- def test_info_escapes_missing_step_id(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog, StepRegistry
+ @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
+ def test_registry_save_preserves_existing_file_mode(self, project_dir):
+ """A registry shared as 0640/0644 must keep that mode after a save,
+ not be silently replaced by mkstemp's 0600 default -- otherwise
+ every add/remove locks other project users out of a previously
+ shared registry file."""
+ from specify_cli.workflows.catalog import WorkflowRegistry
- step_id = "[red]missing[/red]"
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(StepRegistry, "get", lambda _registry, step_id: None)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda _catalog, step_id: None,
- )
+ registry = WorkflowRegistry(project_dir)
+ registry.add("first-wf", {"name": "First"})
+ registry.registry_path.chmod(0o644)
- result = CliRunner().invoke(
- app, ["workflow", "step", "info", step_id]
- )
+ registry.add("second-wf", {"name": "Second"})
- assert result.exit_code == 1, result.output
- assert step_id in result.output
+ mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
+ assert mode == 0o644, f"expected 0644, got {oct(mode)}"
- def test_list_escapes_installed_metadata(
+ @pytest.mark.skipif(not hasattr(os, "fchown"), reason="os.fchown is unavailable")
+ def test_registry_save_preserves_existing_owner_group(
self, project_dir, monkeypatch
):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepRegistry
+ from specify_cli.workflows.catalog import WorkflowRegistry
+ import specify_cli.workflows.catalog as catalog_mod
- metadata = dict(self.METADATA)
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- StepRegistry,
- "list",
- lambda _registry: {metadata["id"]: metadata},
- )
-
- result = CliRunner().invoke(app, ["workflow", "step", "list"])
-
- assert result.exit_code == 0, result.output
- assert metadata["name"] in result.output
- assert metadata["id"] in result.output
- assert metadata["version"] in result.output
-
-
-class TestWorkflowStepAddCLI:
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_add_rejects_symlinked_steps_base_dir(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- outside = project_dir.parent / "outside-steps"
- outside.mkdir(parents=True, exist_ok=True)
- steps_link = project_dir / ".specify" / "workflows" / "steps"
- steps_link.symlink_to(outside, target_is_directory=True)
-
- def _fake_get_step_info(self, step_id):
- return {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- }
-
- monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
-
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
-
- assert result.exit_code != 0
- assert "Refusing to use symlinked step directory" in result.output
-
- def test_add_rejects_oversized_step_response(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
- from specify_cli.workflows.catalog import StepCatalog
- from specify_cli.authentication import http as auth_http
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- },
- )
-
- class _FakeResponse:
- def __init__(self, url):
- self.url = url
- self.body = b"x" * 500
- self.offset = 0
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def getheader(self, name):
- return None
-
- def geturl(self):
- return self.url
-
- def read(self, size=-1):
- if size < 0:
- size = len(self.body) - self.offset
- chunk = self.body[self.offset : self.offset + size]
- self.offset += len(chunk)
- return chunk
-
- monkeypatch.setattr(
- auth_http,
- "open_url",
- lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code != 0
- assert (
- "responseexceedsthe100-byteworkflowsizelimit"
- in "".join(result.output.split())
- )
- assert not (
- project_dir / ".specify" / "workflows" / "steps" / "my-step"
- ).exists()
-
- @pytest.mark.parametrize(
- "step_yml_body", [b"[]", b"false", b"0", b"''", b"null", b"~", b"NULL"]
- )
- def test_add_rejects_falsy_non_mapping_step_yml(
- self, project_dir, monkeypatch, step_yml_body
- ):
- """A FALSY non-mapping step.yml document ([], false, 0, '') must be
- reported as "step.yml must be a YAML mapping", not silently coerced by
- ``or {}`` into {} and then misreported as the unrelated "missing
- 'step.type_key'" error — matching how a TRUTHY non-mapping document
- (e.g. a bare string) already reports the mapping-shape error. An
- explicit null scalar (null/~/NULL) parses to the same ``None`` as a
- genuinely empty document, so it must be distinguished (via
- ``yaml.compose``) and rejected too, rather than defaulting to {}."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
- from specify_cli.authentication import http as auth_http
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- },
- )
-
- class _FakeResponse:
- def __init__(self, url):
- self.url = url
- self.body = step_yml_body if url.endswith("step.yml") else b""
- self.offset = 0
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def getheader(self, name):
- return None
-
- def geturl(self):
- return self.url
-
- def read(self, size=-1):
- if size < 0:
- size = len(self.body) - self.offset
- chunk = self.body[self.offset : self.offset + size]
- self.offset += len(chunk)
- return chunk
-
- monkeypatch.setattr(
- auth_http,
- "open_url",
- lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code != 0
- assert "step.yml must be a YAML mapping" in result.output
- assert not (
- project_dir / ".specify" / "workflows" / "steps" / "my-step"
- ).exists()
-
- @pytest.mark.parametrize(
- ("catalog_fields", "expected"),
- [
- ({"url": 123}, "malformed step.yml URL"),
- (
- {
- "step_yml_url": [],
- "url": "https://example.com/step.yml",
- },
- "malformed step.yml URL",
- ),
- (
- {
- "url": "https://example.com/step.yml",
- "init_url": 123,
- },
- "malformed __init__.py URL",
- ),
- ],
- )
- def test_add_rejects_non_string_required_urls_before_network(
- self, project_dir, monkeypatch, catalog_fields, expected
- ):
- from typer.testing import CliRunner
-
- from specify_cli import app
- from specify_cli.authentication import http as auth_http
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "_install_allowed": True,
- **catalog_fields,
- },
- )
- monkeypatch.setattr(
- auth_http,
- "open_url",
- lambda *args, **kwargs: (_ for _ in ()).throw(
- AssertionError("download should not start")
- ),
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert expected in result.output
- assert not (
- project_dir / ".specify" / "workflows" / "steps" / "my-step"
- ).exists()
-
- @pytest.mark.parametrize(
- ("alias", "protected_name"),
- [
- ("./step.yml", "step.yml"),
- ("step.yml/", "step.yml"),
- ("STEP.YML", "step.yml"),
- (".\\step.yml", "step.yml"),
- ("./__init__.py", "__init__.py"),
- ("__init__.py/", "__init__.py"),
- ("__INIT__.PY", "__init__.py"),
- (".\\__init__.py", "__init__.py"),
- ],
- )
- def test_add_does_not_overwrite_required_files_through_path_aliases(
- self, project_dir, monkeypatch, alias, protected_name
- ):
- from typer.testing import CliRunner
-
- from specify_cli import app
- from specify_cli.authentication import http as auth_http
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- alias_url = "https://example.com/overwrite"
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {alias: alias_url},
- },
- )
- bodies = {
- "https://example.com/step.yml": b"step:\n type_key: my-step\n",
- "https://example.com/__init__.py": b"# trusted init\n",
- }
- requested_urls: list[str] = []
-
- class _FakeResponse:
- def __init__(self, url):
- self.url = url
- self.body = bodies[url]
- self.offset = 0
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def geturl(self):
- return self.url
-
- def read(self, size=-1):
- if size < 0:
- size = len(self.body) - self.offset
- chunk = self.body[self.offset : self.offset + size]
- self.offset += len(chunk)
- return chunk
-
- def fake_open_url(url, timeout=30, redirect_validator=None):
- requested_urls.append(url)
- return _FakeResponse(url)
-
- monkeypatch.setattr(auth_http, "open_url", fake_open_url)
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code == 0, result.output
- assert alias_url not in requested_urls
- installed_dir = (
- project_dir / ".specify" / "workflows" / "steps" / "my-step"
- )
- assert (installed_dir / protected_name).read_bytes() == bodies[
- f"https://example.com/{protected_name}"
- ]
-
- def test_add_rejects_too_many_package_files_before_network(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
-
- from specify_cli import app
- from specify_cli.authentication import http as auth_http
- from specify_cli.workflows import _commands as workflow_commands
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(workflow_commands, "_MAX_STEP_PACKAGE_FILES", 3)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {
- "one.py": "https://example.com/one.py",
- "two.py": "https://example.com/two.py",
- },
- },
- )
- monkeypatch.setattr(
- auth_http,
- "open_url",
- lambda *args, **kwargs: (_ for _ in ()).throw(
- AssertionError("download should not start")
- ),
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "exceeding the 3-file limit" in result.output
- steps_dir = project_dir / ".specify" / "workflows" / "steps"
- assert not (steps_dir / "my-step").exists()
- assert list(steps_dir.glob("speckit_step_tmp_*")) == []
-
- def test_add_rejects_package_over_cumulative_size_and_cleans_staging(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
-
- from specify_cli import app
- from specify_cli.authentication import http as auth_http
- from specify_cli.workflows import _commands as workflow_commands
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(workflow_commands, "_MAX_STEP_PACKAGE_BYTES", 40)
- monkeypatch.setattr(
- StepCatalog,
- "get_step_info",
- lambda self, step_id: {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {
- "helper.py": "https://example.com/helper.py",
- },
- },
- )
-
- bodies = {
- "https://example.com/step.yml": b"step:\n type_key: my-step\n",
- "https://example.com/__init__.py": b"# init\n",
- "https://example.com/helper.py": b"0123456789",
- }
-
- class _FakeResponse:
- def __init__(self, url):
- self.url = url
- self.body = bodies[url]
- self.offset = 0
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def getheader(self, name):
- return None
-
- def geturl(self):
- return self.url
-
- def read(self, size=-1):
- if size < 0:
- size = len(self.body) - self.offset
- chunk = self.body[self.offset : self.offset + size]
- self.offset += len(chunk)
- return chunk
-
- monkeypatch.setattr(
- auth_http,
- "open_url",
- lambda url, timeout=30, redirect_validator=None: _FakeResponse(url),
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "step", "add", "my-step"]
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "40-byte total size limit" in result.output
- steps_dir = project_dir / ".specify" / "workflows" / "steps"
- assert not (steps_dir / "my-step").exists()
- assert list(steps_dir.glob("speckit_step_tmp_*")) == []
-
- def test_add_rejects_non_string_extra_files_key(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
- from specify_cli.authentication import http as auth_http
-
- monkeypatch.chdir(project_dir)
-
- def _fake_get_step_info(self, step_id):
- return {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {
- 123: "https://example.com/helper.py",
- },
- }
-
- class _FakeResponse:
- def __init__(self, url: str):
- self.url = url
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def read(self, size=-1):
- if getattr(self, "_read", False):
- return b""
- self._read = True
- if self.url.endswith("/step.yml"):
- return b"step:\n type_key: my-step\n"
- return b""
-
- def geturl(self):
- return self.url
-
- def _fake_open_url(url, timeout=30, redirect_validator=None):
- return _FakeResponse(url)
-
- monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
- monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
-
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
-
- assert result.exit_code != 0
- assert "non-string path key" in result.output
-
- @pytest.mark.parametrize(
- "rel_path,expected",
- [
- ("", "empty or non-string path key"),
- (".", "not a valid relative file path"),
- ("..", "not a valid relative file path"),
- ("sub/../x", "not a valid relative file path"),
- ],
- )
- def test_add_rejects_invalid_extra_files_path(
- self, project_dir, monkeypatch, rel_path, expected
- ):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
- from specify_cli.authentication import http as auth_http
-
- monkeypatch.chdir(project_dir)
-
- def _fake_get_step_info(self, step_id):
- return {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {rel_path: "https://example.com/helper.py"},
- }
-
- class _FakeResponse:
- def __init__(self, url: str):
- self.url = url
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def read(self, size=-1):
- if getattr(self, "_read", False):
- return b""
- self._read = True
- if self.url.endswith("/step.yml"):
- return b"step:\n type_key: my-step\n"
- return b""
-
- def geturl(self):
- return self.url
-
- def _fake_open_url(url, timeout=30, redirect_validator=None):
- return _FakeResponse(url)
-
- monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
- monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
-
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
-
- assert result.exit_code != 0
- assert expected in result.output
-
- def test_add_rejects_non_string_extra_files_url(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
- from specify_cli.authentication import http as auth_http
-
- monkeypatch.chdir(project_dir)
-
- def _fake_get_step_info(self, step_id):
- return {
- "id": step_id,
- "name": "Test Step",
- "url": "https://example.com/step.yml",
- "init_url": "https://example.com/__init__.py",
- "_install_allowed": True,
- "extra_files": {"helper.py": None},
- }
-
- class _FakeResponse:
- def __init__(self, url: str):
- self.url = url
-
- def __enter__(self):
- return self
-
- def __exit__(self, exc_type, exc, tb):
- return False
-
- def read(self, size=-1):
- if getattr(self, "_read", False):
- return b""
- self._read = True
- if self.url.endswith("/step.yml"):
- return b"step:\n type_key: my-step\n"
- return b""
-
- def geturl(self):
- return self.url
-
- def _fake_open_url(url, timeout=30, redirect_validator=None):
- return _FakeResponse(url)
-
- monkeypatch.setattr(StepCatalog, "get_step_info", _fake_get_step_info)
- monkeypatch.setattr(auth_http, "open_url", _fake_open_url)
-
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "add", "my-step"])
-
- assert result.exit_code != 0
- assert "empty or non-string URL" in result.output
-
-
-class TestWorkflowJsonOutput:
- """Test the --json machine-readable output for run/resume/status."""
-
- _WF = """
-schema_version: "1.0"
-workflow:
- id: "json-wf"
- name: "JSON WF"
- version: "1.0.0"
-steps:
- - id: ask
- type: gate
- message: "Review"
- options: [approve, reject]
- - id: after
- type: shell
- run: "echo done"
-"""
-
- _WF_DONE = """
-schema_version: "1.0"
-workflow:
- id: "json-done"
- name: "JSON Done"
- version: "1.0.0"
-steps:
- - id: only
- type: shell
- run: "echo done"
-"""
-
- _WF_FAIL = """
-schema_version: "1.0"
-workflow:
- id: "json-fail"
- name: "JSON Fail"
- version: "1.0.0"
-steps:
- - id: boom
- type: shell
- run: "exit 3"
-"""
-
- def _write_wf(self, project_dir, text, name):
- path = project_dir / f"{name}.yml"
- path.write_text(text, encoding="utf-8")
- return path
-
- def _invoke(self, project_dir, args):
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir):
- return runner.invoke(app, args, catch_exceptions=False)
-
- def test_run_json_completed(self, project_dir):
- wf = self._write_wf(project_dir, self._WF_DONE, "done")
- result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
- assert result.exit_code == 0
- payload = json.loads(result.stdout)
- assert payload["workflow_id"] == "json-done"
- assert payload["status"] == "completed"
- assert "run_id" in payload
-
- def test_run_json_paused(self, project_dir):
- wf = self._write_wf(project_dir, self._WF, "gated")
- result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
- assert result.exit_code == 0
- payload = json.loads(result.stdout)
- assert payload["status"] == "paused"
- assert payload["current_step_id"] == "ask"
- assert payload["current_step_index"] == 0
-
- def test_run_json_failed_includes_error(self, project_dir):
- # A run that ends in `failed` (a step failing, not an exception) must
- # carry the persisted step error in the JSON payload so external
- # callers get a reason, not a bare {"status": "failed"}.
- wf = self._write_wf(project_dir, self._WF_FAIL, "boom")
- result = self._invoke(project_dir, ["workflow", "run", str(wf), "--json"])
- assert result.exit_code != 0
- payload = json.loads(result.stdout)
- assert payload["status"] == "failed"
- assert payload.get("error")
-
- def test_status_json_failed_includes_error(self, project_dir):
- # `status --json` reuses the shared payload, so a failed run inspected
- # after the fact surfaces the same error text as `run`/`resume`.
- wf = self._write_wf(project_dir, self._WF_FAIL, "boom2")
- rid = json.loads(
- self._invoke(
- project_dir, ["workflow", "run", str(wf), "--json"]
- ).stdout
- )["run_id"]
- status = json.loads(
- self._invoke(
- project_dir, ["workflow", "status", rid, "--json"]
- ).stdout
- )
- assert status["status"] == "failed"
- assert status.get("error")
-
- def test_run_json_completed_omits_error(self, project_dir):
- # Successful runs must not carry an `error` key at all.
- wf = self._write_wf(project_dir, self._WF_DONE, "noerr")
- payload = json.loads(
- self._invoke(
- project_dir, ["workflow", "run", str(wf), "--json"]
- ).stdout
- )
- assert payload["status"] == "completed"
- assert "error" not in payload
-
- def test_run_json_output_has_no_markup_or_ansi(self, project_dir):
- wf = self._write_wf(project_dir, self._WF_DONE, "clean")
- out = self._invoke(
- project_dir, ["workflow", "run", str(wf), "--json"]
- ).stdout
- # Machine output must be exactly the JSON object: no Rich markup
- # tags and no ANSI escape sequences leaking in.
- assert "\x1b[" not in out
- assert "[/" not in out
- assert out.strip() == json.dumps(json.loads(out), indent=2)
-
- def test_run_default_output_is_human_not_json(self, project_dir):
- wf = self._write_wf(project_dir, self._WF_DONE, "done2")
- result = self._invoke(project_dir, ["workflow", "run", str(wf)])
- assert result.exit_code == 0
- assert "Running workflow" in result.stdout
- with pytest.raises(json.JSONDecodeError):
- json.loads(result.stdout)
-
- def test_status_json_single_and_list(self, project_dir):
- wf = self._write_wf(project_dir, self._WF, "gated2")
- run = json.loads(
- self._invoke(project_dir, ["workflow", "run", str(wf), "--json"]).stdout
- )
- rid = run["run_id"]
-
- single = json.loads(
- self._invoke(project_dir, ["workflow", "status", rid, "--json"]).stdout
- )
- assert single["run_id"] == rid
- assert single["status"] == "paused"
- assert single["steps"]["ask"] == "paused"
- # status --json carries the same step-position fields as run/resume
- # so automation never has to branch on which command produced it.
- assert single["current_step_id"] == run["current_step_id"]
- assert single["current_step_index"] == run["current_step_index"]
-
- listing = json.loads(
- self._invoke(project_dir, ["workflow", "status", "--json"]).stdout
- )
- assert any(r["run_id"] == rid for r in listing["runs"])
-
- def test_resume_json(self, project_dir):
- wf = self._write_wf(project_dir, self._WF, "gated3")
- rid = json.loads(
- self._invoke(project_dir, ["workflow", "run", str(wf), "--json"]).stdout
- )["run_id"]
- # Non-interactive resume re-runs the gate, which pauses again.
- resumed = json.loads(
- self._invoke(project_dir, ["workflow", "resume", rid, "--json"]).stdout
- )
- assert resumed["run_id"] == rid
- assert resumed["status"] == "paused"
-
- def test_json_redirect_keeps_stdout_clean(self, capfd):
- # While a workflow runs under --json, steps can still write to stdout:
- # the gate step prints its prompt and the prompt step runs a
- # subprocess that inherits the stdout fd. Both must be redirected to
- # stderr so the JSON object on stdout stays parseable. capfd captures
- # at the file-descriptor level, so it sees the subprocess output too.
- import subprocess
- import sys as _sys
- from specify_cli.workflows._commands import _stdout_to_stderr_when
-
- print("STDOUT_BEFORE")
- with _stdout_to_stderr_when(True):
- print("PY_LEAK") # Python-level write (gate-style)
- subprocess.run( # inherited-fd write (prompt-style)
- [_sys.executable, "-c", "print('SUBPROC_LEAK')"],
- check=True,
- )
- print("STDOUT_AFTER")
-
- out, err = capfd.readouterr()
- # stdout keeps only what was written outside the guarded block.
- assert "STDOUT_BEFORE" in out and "STDOUT_AFTER" in out
- assert "PY_LEAK" not in out and "SUBPROC_LEAK" not in out
- # The step output is preserved on stderr, not discarded.
- assert "PY_LEAK" in err and "SUBPROC_LEAK" in err
-
- def test_json_redirect_inactive_is_noop(self, capfd):
- from specify_cli.workflows._commands import _stdout_to_stderr_when
-
- with _stdout_to_stderr_when(False):
- print("VISIBLE_ON_STDOUT")
- out, _ = capfd.readouterr()
- assert "VISIBLE_ON_STDOUT" in out
-
-
-class TestResumeWithInputs:
- """Test that `workflow resume` can accept updated workflow inputs."""
-
- _WF_CMD = """
-schema_version: "1.0"
-workflow:
- id: "resume-cmd-wf"
- name: "Resume Cmd WF"
- version: "1.0.0"
-inputs:
- cmd:
- type: string
- default: "exit 1"
-steps:
- - id: s
- type: shell
- run: "{{ inputs.cmd }}"
-"""
-
- _WF_NUM = """
-schema_version: "1.0"
-workflow:
- id: "resume-num-wf"
- name: "Resume Num WF"
- version: "1.0.0"
-inputs:
- count:
- type: number
- default: 1
-steps:
- - id: gate
- type: gate
- message: "Review"
- options: [approve, reject]
-"""
-
- _WF_GATE_VERDICT = """
-schema_version: "1.0"
-workflow:
- id: "resume-gate-verdict-wf"
- name: "Resume Gate Verdict WF"
- version: "1.0.0"
-inputs:
- spec_verdict:
- type: string
- default: ""
-steps:
- - id: gate
- type: gate
- message: "Review"
- options: [approve, reject]
- on_reject: retry
- verdict_input: spec_verdict
-"""
-
- _WF_RUNTIME_CONFIG = """
-schema_version: "1.0"
-workflow:
- id: "resume-runtime-config-wf"
- name: "Resume Runtime Config WF"
- version: "1.0.0"
-inputs:
- config:
- type: string
- default: "./initial-agent.yaml"
- agent_name:
- type: string
- default: "initial-root"
- model_name:
- type: string
- default: "initial/model"
-steps:
- - id: implement
- type: command
- command: speckit.implement
- integration: docker-agent
- integration_args:
- - "{{ inputs.config }}"
- integration_options:
- agent: "{{ inputs.agent_name }}"
- safety: balanced
- model: "{{ inputs.model_name }}"
-"""
-
- _WF_DYNAMIC_INTEGRATION = """
-schema_version: "1.0"
-workflow:
- id: "resume-dynamic-integration-wf"
- name: "Resume Dynamic Integration WF"
- version: "1.0.0"
-inputs:
- integration:
- type: string
- default: docker-agent
- config:
- type: string
- default: "./initial-agent.yaml"
-steps:
- - id: implement
- type: command
- command: speckit.implement
- integration: "{{ inputs.integration }}"
- integration_args:
- - "{{ inputs.config }}"
-"""
-
- def _engine(self, project_dir):
- from specify_cli.workflows.engine import WorkflowEngine
- return WorkflowEngine(project_dir)
-
- def test_resume_with_input_reruns_step_with_new_value(self, project_dir):
- from specify_cli.workflows.engine import WorkflowDefinition
- from specify_cli.workflows.base import RunStatus
-
- definition = WorkflowDefinition.from_string(self._WF_CMD)
- engine = self._engine(project_dir)
-
- state = engine.execute(definition)
- assert state.status == RunStatus.FAILED # "exit 1" fails
-
- resumed = engine.resume(state.run_id, {"cmd": "exit 0"})
- assert resumed.status == RunStatus.COMPLETED
- assert resumed.inputs["cmd"] == "exit 0"
-
- def test_resume_without_input_preserves_inputs(self, project_dir):
- from specify_cli.workflows.engine import WorkflowDefinition
- from specify_cli.workflows.base import RunStatus
-
- definition = WorkflowDefinition.from_string(self._WF_CMD)
- engine = self._engine(project_dir)
-
- state = engine.execute(definition)
- assert state.status == RunStatus.FAILED
-
- resumed = engine.resume(state.run_id)
- assert resumed.status == RunStatus.FAILED # still "exit 1"
- assert resumed.inputs["cmd"] == "exit 1"
-
- def test_resume_re_resolves_complete_integration_config(
- self, project_dir, monkeypatch
- ):
- from specify_cli.workflows.base import RunStatus
- from specify_cli.workflows.engine import WorkflowDefinition
-
- calls = []
- return_codes = iter((1, 0))
-
- def fake_run(args, **kwargs):
- calls.append(args)
- return type("Result", (), {"returncode": next(return_codes)})()
-
- monkeypatch.delenv(
- "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
- )
- monkeypatch.setattr(
- "shutil.which",
- lambda name: (
- "/usr/bin/docker-agent"
- if name in {"docker-agent", "/usr/bin/docker-agent"}
- else None
- ),
- )
- monkeypatch.setattr("subprocess.run", fake_run)
-
- definition = WorkflowDefinition.from_string(self._WF_RUNTIME_CONFIG)
- engine = self._engine(project_dir)
- state = engine.execute(definition)
-
- assert state.status is RunStatus.FAILED
- assert state.step_results["implement"]["integration_args"] == [
- "./initial-agent.yaml"
- ]
- assert state.step_results["implement"]["integration_options"] == {
- "agent": "initial-root",
- "safety": "balanced",
- }
-
- resumed = engine.resume(
- state.run_id,
- {
- "config": "./changed-on-resume.yaml",
- "agent_name": "changed-root",
- "model_name": "changed/model",
- },
- )
-
- assert resumed.status is RunStatus.COMPLETED
- assert resumed.inputs["config"] == "./changed-on-resume.yaml"
- assert len(calls) == 2
- assert "./initial-agent.yaml" in calls[0]
- assert "./changed-on-resume.yaml" in calls[1]
- assert "./initial-agent.yaml" not in calls[1]
- assert calls[1][calls[1].index("--agent") + 1] == "changed-root"
- assert calls[1][calls[1].index("--model") + 1] == "changed/model"
-
- def test_resume_does_not_mix_new_integration_with_old_runtime_config(
- self, project_dir, monkeypatch
- ):
- from specify_cli.workflows.base import RunStatus
- from specify_cli.workflows.engine import WorkflowDefinition
-
- monkeypatch.delenv(
- "SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS", raising=False
- )
- monkeypatch.setattr(
- "shutil.which",
- lambda name: (
- "/usr/bin/docker-agent"
- if name in {"docker-agent", "/usr/bin/docker-agent"}
- else None
- ),
- )
- monkeypatch.setattr(
- "subprocess.run",
- lambda *args, **kwargs: type("Result", (), {"returncode": 1})(),
- )
-
- definition = WorkflowDefinition.from_string(self._WF_DYNAMIC_INTEGRATION)
- engine = self._engine(project_dir)
- state = engine.execute(definition)
- assert state.status is RunStatus.FAILED
-
- resumed = engine.resume(
- state.run_id,
- {"integration": "claude", "config": "./changed-on-resume.yaml"},
- )
-
- assert resumed.status is RunStatus.FAILED
- step_result = resumed.step_results["implement"]
- assert step_result["integration"] == "claude"
- assert step_result["integration_args"] == ["./changed-on-resume.yaml"]
- assert "Integration 'claude'" in (step_result["error"] or "")
- assert "./initial-agent.yaml" not in str(step_result)
-
- def test_resume_merges_and_coerces_typed_input(self, project_dir):
- import json as _json
- from specify_cli.workflows.engine import WorkflowDefinition
- from specify_cli.workflows.base import RunStatus
-
- definition = WorkflowDefinition.from_string(self._WF_NUM)
- engine = self._engine(project_dir)
-
- state = engine.execute(definition)
- assert state.status == RunStatus.PAUSED
-
- resumed = engine.resume(state.run_id, {"count": "5"})
- assert resumed.inputs["count"] == 5 # coerced string -> number
-
- inputs_file = (
- project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
- )
- assert _json.loads(inputs_file.read_text())["inputs"]["count"] == 5
-
- def test_resume_invalid_typed_input_raises(self, project_dir):
- from specify_cli.workflows.engine import WorkflowDefinition
-
- definition = WorkflowDefinition.from_string(self._WF_NUM)
- engine = self._engine(project_dir)
-
- state = engine.execute(definition)
- with pytest.raises(ValueError):
- engine.resume(state.run_id, {"count": "not-a-number"})
-
- def test_resume_rejects_legacy_invalid_options_before_state_mutation(
- self, project_dir, monkeypatch
- ):
- from specify_cli.workflows.base import RunStatus
- from specify_cli.workflows.engine import RunState, WorkflowDefinition
-
- definition = WorkflowDefinition.from_string(self._WF_NUM)
- engine = self._engine(project_dir)
- state = engine.execute(definition)
- assert state.status == RunStatus.PAUSED
-
- workflow_copy = (
- project_dir
- / ".specify"
- / "workflows"
- / "runs"
- / state.run_id
- / "workflow.yml"
- )
- workflow_copy.write_text(
- self._WF_NUM.replace(
- 'version: "1.0.0"', 'version: "1.0.0"\n options: [max_tokens]'
- ),
- encoding="utf-8",
- )
-
- def fail_step_context(*args, **kwargs):
- raise AssertionError("StepContext must not be created")
-
- monkeypatch.setattr("specify_cli.workflows.engine.StepContext", fail_step_context)
-
- with pytest.raises(ValueError, match="'workflow.options' must be a mapping or null"):
- engine.resume(state.run_id, {"count": "5"})
-
- reloaded = RunState.load(state.run_id, project_dir)
- assert reloaded.status == RunStatus.PAUSED
- assert reloaded.error is None
- assert reloaded.inputs["count"] == 1
-
- def test_retry_verdict_input_is_consumed_and_can_be_replaced(self, project_dir):
- import json as _json
- from specify_cli.workflows.engine import WorkflowDefinition
- from specify_cli.workflows.base import RunStatus
-
- definition = WorkflowDefinition.from_string(self._WF_GATE_VERDICT)
- engine = self._engine(project_dir)
-
- state = engine.execute(definition, {"spec_verdict": "reject"})
- assert state.status == RunStatus.PAUSED
- assert state.inputs["spec_verdict"] == ""
-
- inputs_file = (
- project_dir / ".specify" / "workflows" / "runs" / state.run_id / "inputs.json"
- )
- assert _json.loads(inputs_file.read_text())["inputs"]["spec_verdict"] == ""
-
- paused_again = engine.resume(state.run_id)
- assert paused_again.status == RunStatus.PAUSED
- assert paused_again.inputs["spec_verdict"] == ""
-
- completed = engine.resume(state.run_id, {"spec_verdict": "approve"})
- assert completed.status == RunStatus.COMPLETED
- assert completed.step_results["gate"]["output"]["choice"] == "approve"
-
- def test_cli_resume_input_invalid_format_errors(self, project_dir):
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowDefinition
-
- definition = WorkflowDefinition.from_string(self._WF_NUM)
- state = self._engine(project_dir).execute(definition)
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir):
- result = runner.invoke(
- app, ["workflow", "resume", state.run_id, "--input", "bogus"]
- )
- assert result.exit_code == 1
- assert "Invalid input format" in result.stdout
-
-
-class TestWorkflowAddUrlResolution:
- """CLI-level tests for workflow add <url> GitHub release URL resolution."""
-
- VALID_WORKFLOW_YAML = """
-schema_version: "1.0"
-workflow:
- id: "test-wf"
- name: "Test Workflow"
- version: "1.0.0"
- description: "A test workflow"
-steps:
- - id: step-one
- type: shell
- run: "echo hello"
-"""
-
- def test_workflow_add_from_github_release_url_resolves_and_downloads(self, project_dir):
- """'workflow add <github-release-url>' resolves to API asset URL."""
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
-
- captured_urls = []
-
- class FakeResponse:
- def __init__(self, data, url=None):
- self._data = data
- self._pos = 0
- self._url = url or "https://api.github.com/repos/org/repo/releases/assets/42"
-
- def read(self, size=-1):
- if size < 0:
- size = len(self._data) - self._pos
- out = self._data[self._pos : self._pos + size]
- self._pos += len(out)
- return out
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- captured_urls.append(
- (url, extra_headers, timeout, redirect_validator)
- )
- if "releases/tags/" in url:
- return FakeResponse(json.dumps({
- "assets": [{"name": "workflow.yml", "url": "https://api.github.com/repos/org/repo/releases/assets/42"}]
- }).encode())
- return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir), \
- patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
- result = runner.invoke(app, [
- "workflow", "add",
- "https://github.com/org/repo/releases/download/v1.0/workflow.yml",
- ])
-
- assert result.exit_code == 0, result.output
- assert "Test Workflow" in result.output
- # First call resolves the release tag with timeout=30
- tag_calls = [
- (url, headers, timeout, validator)
- for url, headers, timeout, validator in captured_urls
- if "releases/tags/" in url
- ]
- assert len(tag_calls) == 1
- assert tag_calls[0][2] == 30 # timeout matches download timeout
- assert tag_calls[0][3] is not None
- # Second call downloads from the resolved asset URL with octet-stream
- asset_calls = [
- (url, headers, timeout, validator)
- for url, headers, timeout, validator in captured_urls
- if "releases/assets/" in url
- ]
- assert len(asset_calls) >= 1
- assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
-
- def test_workflow_add_from_direct_api_asset_url_passes_through(self, project_dir):
- """'workflow add <api-asset-url>' uses URL directly with octet-stream."""
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
-
- captured_urls = []
-
- class FakeResponse:
- def __init__(self, data, url=None):
- self._data = data
- self._pos = 0
- self._url = url or "https://api.github.com/repos/org/repo/releases/assets/42"
-
- def read(self, size=-1):
- if size < 0:
- size = len(self._data) - self._pos
- out = self._data[self._pos : self._pos + size]
- self._pos += len(out)
- return out
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- captured_urls.append((url, extra_headers))
- return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir), \
- patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
- result = runner.invoke(app, [
- "workflow", "add",
- "https://api.github.com/repos/org/repo/releases/assets/42",
- ])
-
- assert result.exit_code == 0, result.output
- # Should go directly to the asset URL with Accept header
- assert len(captured_urls) == 1
- assert captured_urls[0][0] == "https://api.github.com/repos/org/repo/releases/assets/42"
- assert captured_urls[0][1] == {"Accept": "application/octet-stream"}
-
- def test_workflow_add_catalog_based_resolves_github_release_url(self, project_dir):
- """'workflow add <id>' with catalog GitHub release URL resolves via API."""
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
-
- captured_urls = []
-
- class FakeResponse:
- def __init__(self, data, url=None):
- self._data = data
- self._pos = 0
- self._url = url or "https://api.github.com/repos/org/repo/releases/assets/55"
-
- def read(self, size=-1):
- if size < 0:
- size = len(self._data) - self._pos
- out = self._data[self._pos : self._pos + size]
- self._pos += len(out)
- return out
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- captured_urls.append((url, extra_headers, redirect_validator))
- if "releases/tags/" in url:
- return FakeResponse(json.dumps({
- "assets": [{"name": "workflow.yml", "url": "https://api.github.com/repos/org/repo/releases/assets/55"}]
- }).encode())
- # Use workflow YAML with id matching catalog key
- wf_yaml = """
-schema_version: "1.0"
-workflow:
- id: "my-wf"
- name: "My Workflow"
- version: "1.0.0"
- description: "A catalog workflow"
-steps:
- - id: step-one
- type: shell
- run: "echo hello"
-"""
- return FakeResponse(wf_yaml.encode())
-
- fake_catalog_info = {
- "id": "my-wf",
- "name": "My Workflow",
- "version": "1.0.0",
- "url": "https://github.com/org/repo/releases/download/v2.0/workflow.yml",
- "_install_allowed": True,
- }
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir), \
- patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url), \
- patch("specify_cli.workflows.catalog.WorkflowCatalog.get_workflow_info", return_value=fake_catalog_info):
- result = runner.invoke(app, ["workflow", "add", "my-wf"])
-
- assert result.exit_code == 0, result.output
- # Should resolve via releases/tags API
- tag_calls = [
- (url, validator)
- for url, _, validator in captured_urls
- if "releases/tags/" in url
- ]
- assert len(tag_calls) == 1
- assert "releases/tags/v2.0" in tag_calls[0][0]
- assert tag_calls[0][1] is not None
- # Should download from resolved asset URL with octet-stream
- asset_calls = [
- (url, headers)
- for url, headers, _ in captured_urls
- if "releases/assets/" in url
- ]
- assert len(asset_calls) >= 1
- assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
-
- def test_workflow_add_from_ghes_release_url_resolves_via_api_v3(self, project_dir, monkeypatch):
- """'workflow add <ghes-release-url>' resolves via GHES /api/v3 endpoint."""
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
- from specify_cli.authentication import http as _auth_http
- from specify_cli.authentication.config import AuthConfigEntry
-
- monkeypatch.setattr(_auth_http, "_config_override", [
- AuthConfigEntry(hosts=("ghes.example",), provider="github", auth="bearer", token="t"),
- ])
-
- captured_urls = []
-
- class FakeResponse:
- def __init__(self, data, url=None):
- self._data = data
- self._pos = 0
- self._url = url or "https://ghes.example/api/v3/repos/org/repo/releases/assets/42"
-
- def read(self, size=-1):
- if size < 0:
- size = len(self._data) - self._pos
- out = self._data[self._pos : self._pos + size]
- self._pos += len(out)
- return out
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- captured_urls.append((url, extra_headers))
- if "releases/tags/" in url:
- return FakeResponse(json.dumps({
- "assets": [{"name": "workflow.yml", "url": "https://ghes.example/api/v3/repos/org/repo/releases/assets/42"}]
- }).encode())
- return FakeResponse(self.VALID_WORKFLOW_YAML.encode())
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir), \
- patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url):
- result = runner.invoke(app, [
- "workflow", "add",
- "https://ghes.example/org/repo/releases/download/v1.0/workflow.yml",
- ])
-
- assert result.exit_code == 0, result.output
- # Tag lookup must use the GHES /api/v3 endpoint
- assert any("ghes.example/api/v3/repos/org/repo/releases/tags/v1.0" in url for url, _ in captured_urls)
- # Asset download must carry Accept: application/octet-stream
- asset_calls = [(url, h) for url, h in captured_urls if "releases/assets/" in url]
- assert len(asset_calls) >= 1
- assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
-
- def test_workflow_add_catalog_based_ghes_release_url_resolves_via_api_v3(self, project_dir, monkeypatch):
- """'workflow add <id>' with a GHES catalog URL resolves via /api/v3."""
- from typer.testing import CliRunner
- from unittest.mock import patch
- from specify_cli import app
- from specify_cli.authentication import http as _auth_http
- from specify_cli.authentication.config import AuthConfigEntry
-
- monkeypatch.setattr(_auth_http, "_config_override", [
- AuthConfigEntry(hosts=("ghes.example",), provider="github", auth="bearer", token="t"),
- ])
-
- captured_urls = []
-
- class FakeResponse:
- def __init__(self, data, url=None):
- self._data = data
- self._pos = 0
- self._url = url or "https://ghes.example/api/v3/repos/org/repo/releases/assets/55"
-
- def read(self, size=-1):
- if size < 0:
- size = len(self._data) - self._pos
- out = self._data[self._pos : self._pos + size]
- self._pos += len(out)
- return out
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- ghes_wf_yaml = """
-schema_version: "1.0"
-workflow:
- id: "my-wf"
- name: "My GHES Workflow"
- version: "1.0.0"
- description: "A GHES catalog workflow"
-steps:
- - id: step-one
- type: shell
- run: "echo hello"
-"""
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- captured_urls.append((url, extra_headers))
- if "releases/tags/" in url:
- return FakeResponse(json.dumps({
- "assets": [{"name": "workflow.yml", "url": "https://ghes.example/api/v3/repos/org/repo/releases/assets/55"}]
- }).encode())
- return FakeResponse(ghes_wf_yaml.encode())
-
- fake_catalog_info = {
- "id": "my-wf",
- "name": "My GHES Workflow",
- "version": "1.0.0",
- "url": "https://ghes.example/org/repo/releases/download/v2.0/workflow.yml",
- "_install_allowed": True,
- }
-
- runner = CliRunner()
- with patch.object(Path, "cwd", return_value=project_dir), \
- patch("specify_cli.authentication.http.open_url", side_effect=fake_open_url), \
- patch("specify_cli.workflows.catalog.WorkflowCatalog.get_workflow_info", return_value=fake_catalog_info):
- result = runner.invoke(app, ["workflow", "add", "my-wf"])
-
- assert result.exit_code == 0, result.output
- # Tag lookup must use GHES /api/v3
- tag_calls = [url for url, _ in captured_urls if "releases/tags/" in url]
- assert len(tag_calls) == 1
- assert "ghes.example/api/v3/repos/org/repo/releases/tags/v2.0" in tag_calls[0]
- # Asset download must carry Accept: application/octet-stream
- asset_calls = [(url, h) for url, h in captured_urls if "releases/assets/" in url]
- assert len(asset_calls) >= 1
- assert asset_calls[0][1] == {"Accept": "application/octet-stream"}
-
-
-class TestWorkflowStepStartProgressLine:
- """The `run`/`resume` step-progress line must render the step id literally.
-
- The line is built as ` ▸ [<id>] <label> …`, so Rich parsed the bracketed id
- as a style tag: it silently swallowed the id (the only identifying content
- on the line), applied it as formatting when the id happened to be a real
- style like `bold`, and raised MarkupError — failing the whole run — when the
- id formed a closing tag such as `/`. `validate_workflow` places no charset
- restriction on step ids, so all of these are accepted workflows.
- """
-
- def _write(self, tmp_path, step_id):
- path = tmp_path / "wf.yml"
- path.write_text(
- 'schema_version: "1.0"\n'
- "workflow:\n"
- ' id: "probe-wf"\n'
- ' name: "Probe"\n'
- ' version: "1.0.0"\n'
- "steps:\n"
- f' - id: "{step_id}"\n'
- " type: shell\n"
- ' run: "exit 0"\n',
- encoding="utf-8",
- )
- return path
-
- @pytest.mark.parametrize("step_id", ["greet", "bold", "a]b"])
- def test_progress_line_shows_step_id(self, tmp_path, monkeypatch, step_id):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- result = CliRunner().invoke(
- app, ["workflow", "run", str(self._write(tmp_path, step_id))]
- )
- assert result.exit_code == 0, result.stdout
- assert f"[{step_id}]" in result.stdout
-
- def test_step_id_forming_a_closing_tag_does_not_fail_the_run(
- self, tmp_path, monkeypatch
- ):
- """`id: "/"` raised MarkupError from inside the progress callback, which
- surfaced as a failed run with no step results."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- result = CliRunner().invoke(
- app, ["workflow", "run", str(self._write(tmp_path, "/"))]
- )
- assert result.exit_code == 0, result.stdout
- assert "Status: completed" in result.stdout
- assert "[/]" in result.stdout
-
- def test_resume_progress_line_shows_step_id(self, tmp_path, monkeypatch):
- """`workflow resume` installs its own copy of the same callback, so it
- needs independent coverage — a one-line fix would miss the twin."""
- import json as _json
-
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- path = tmp_path / "wf.yml"
- path.write_text(
- 'schema_version: "1.0"\n'
- "workflow:\n"
- ' id: "probe-resume"\n'
- ' name: "Probe"\n'
- ' version: "1.0.0"\n'
- "steps:\n"
- " - id: boom\n"
- " type: shell\n"
- ' run: "exit 1"\n',
- encoding="utf-8",
- )
- runner = CliRunner()
- first = runner.invoke(app, ["workflow", "run", str(path), "--json"])
- run_id = _json.loads(first.stdout).get("run_id")
- assert run_id
-
- resumed = runner.invoke(app, ["workflow", "resume", run_id])
- assert "[boom]" in resumed.stdout
-
-
-class TestWorkflowRunExitCodes:
- """CLI-level tests for the run/resume process exit codes."""
-
- _WF_OK = """
-schema_version: "1.0"
-workflow:
- id: "exit-ok"
- name: "Exit OK"
- version: "1.0.0"
-steps:
- - id: fine
- type: shell
- run: "exit 0"
-"""
-
- _WF_FAIL = """
-schema_version: "1.0"
-workflow:
- id: "exit-fail"
- name: "Exit Fail"
- version: "1.0.0"
-steps:
- - id: boom
- type: shell
- run: "exit 1"
-"""
-
- def _write(self, tmp_path, content):
- path = tmp_path / "wf.yml"
- path.write_text(content, encoding="utf-8")
- return path
-
- def test_run_completed_exits_zero(self, tmp_path, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "run", str(self._write(tmp_path, self._WF_OK))])
- assert result.exit_code == 0
- assert "Status: completed" in result.stdout
-
- def test_run_failed_exits_nonzero(self, tmp_path, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL))])
- assert "Status: failed" in result.stdout
- assert result.exit_code == 1
-
- def test_run_failed_exits_nonzero_with_json(self, tmp_path, monkeypatch):
- import json as _json
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(
- app,
- ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL)), "--json"],
- )
- assert result.exit_code == 1, result.stdout
- payload = _json.loads(result.stdout)
- assert payload["status"] == "failed"
-
- def test_resume_failed_run_exits_nonzero(self, tmp_path, monkeypatch):
- # End-to-end coverage for the `workflow resume` exit-code mapping:
- # resuming a run whose outcome is still `failed` must exit non-zero,
- # mirroring `workflow run`. Resume re-executes the failed step, which
- # fails again, so the resumed outcome stays `failed`.
- import json as _json
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- (tmp_path / ".specify").mkdir() # `workflow resume` requires a project
- runner = CliRunner()
- run = runner.invoke(
- app,
- ["workflow", "run", str(self._write(tmp_path, self._WF_FAIL)), "--json"],
- )
- assert run.exit_code == 1, run.stdout
- run_id = _json.loads(run.stdout)["run_id"]
-
- resumed = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert resumed.exit_code == 1, resumed.stdout
- payload = _json.loads(resumed.stdout)
- assert payload["status"] == "failed"
-
- _WF_GATE_INVALID_VERDICT = """
-schema_version: "1.0"
-workflow:
- id: "gate-invalid-verdict"
- name: "Gate Invalid Verdict"
- version: "1.0.0"
-inputs:
- review_verdict:
- type: string
- default: ""
-steps:
- - id: review
- type: gate
- message: "Approve the review?"
- options: [approve, reject]
- on_reject: abort
- verdict_input: review_verdict
-"""
-
- _WF_GATE_INVALID_TYPE = """
-schema_version: "1.0"
-workflow:
- id: "gate-invalid-type"
- name: "Gate Invalid Type"
- version: "1.0.0"
-inputs:
- review_verdict:
- type: number
- default: 1
-steps:
- - id: review
- type: gate
- message: "Approve the review?"
- options: [approve, reject]
- on_reject: abort
- verdict_input: review_verdict
-"""
-
- _WF_GATE_ABORT = """
-schema_version: "1.0"
-workflow:
- id: "gate-abort"
- name: "Gate Abort"
- version: "1.0.0"
-inputs:
- review_verdict:
- type: string
- default: ""
-steps:
- - id: review
- type: gate
- message: "Approve the review?"
- options: [approve, reject]
- on_reject: abort
- verdict_input: review_verdict
-"""
-
- def test_run_invalid_verdict_prints_error(self, tmp_path, monkeypatch):
- """Invalid verdict value prints explanatory error in human output."""
- import re
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(
- app,
- [
- "workflow",
- "run",
- str(self._write(tmp_path, self._WF_GATE_INVALID_VERDICT)),
- "--input",
- "review_verdict=maybe",
- ],
- )
- assert result.exit_code == 1
- assert "Status: failed" in result.stdout
- # Normalize whitespace to handle Rich console line wrapping
- normalized = re.sub(r"\s+", " ", result.stdout)
- assert "does not match any configured option" in normalized
-
- def test_run_invalid_verdict_type_prints_error(self, tmp_path, monkeypatch):
- """Non-string verdict value prints explanatory error in human output."""
- import re
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(
- app,
- ["workflow", "run", str(self._write(tmp_path, self._WF_GATE_INVALID_TYPE))],
- )
- assert result.exit_code == 1
- assert "Status: failed" in result.stdout
- # Normalize whitespace to handle Rich console line wrapping
- normalized = re.sub(r"\s+", " ", result.stdout)
- assert "must be a string" in normalized
-
- def test_run_gate_abort_prints_status_and_error(self, tmp_path, monkeypatch):
- """Gate abort prints Status: aborted and the rejection message."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(
- app,
- [
- "workflow",
- "run",
- str(self._write(tmp_path, self._WF_GATE_ABORT)),
- "--input",
- "review_verdict=reject",
- ],
- )
- assert result.exit_code == 1
- assert "Status: aborted" in result.stdout
- assert "Gate rejected by user" in result.stdout
-
- def test_run_gate_abort_json_includes_error(self, tmp_path, monkeypatch):
- """Gate abort --json includes the rejection message in the error field."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(tmp_path)
- runner = CliRunner()
- result = runner.invoke(
- app,
- [
- "workflow",
- "run",
- str(self._write(tmp_path, self._WF_GATE_ABORT)),
- "--input",
- "review_verdict=reject",
- "--json",
- ],
- )
- assert result.exit_code == 1
- payload = json.loads(result.stdout)
- assert payload["status"] == "aborted"
- assert "Gate rejected by user" in (payload.get("error") or "")
-
-
-class TestWorkflowRunGateOutcomeJson:
- """CLI-level tests: the --json payload surfaces gate pauses."""
-
- _WF_GATE = """
-schema_version: "1.0"
-workflow:
- id: "gate-json"
- name: "Gate JSON"
- version: "1.0.0"
-steps:
- - id: review
- type: gate
- message: "Approve the thing?"
- options: ["approve", "reject"]
-"""
-
- _WF_PLAIN = """
-schema_version: "1.0"
-workflow:
- id: "plain-json"
- name: "Plain JSON"
- version: "1.0.0"
-steps:
- - id: fine
- type: shell
- run: "exit 0"
-"""
-
- def _run_json(self, tmp_path, monkeypatch, content, *, expected_exit=0):
- import json as _json
- from typer.testing import CliRunner
- from specify_cli import app
-
- path = tmp_path / "wf.yml"
- path.write_text(content, encoding="utf-8")
- monkeypatch.chdir(tmp_path)
- result = CliRunner().invoke(app, ["workflow", "run", str(path), "--json"])
- # Assert the expected exit code before parsing so a real failure
- # surfaces the actual output instead of an opaque JSON decode error.
- # A terminal run still emits its JSON payload, then exits non-zero on
- # ``failed``/``aborted`` (see ``_run_outcome_exit_code``), so callers
- # pass the expected code. Use ``result.output`` for the message:
- # under ``--json`` step output is redirected off stdout, so the useful
- # diagnostics live there.
- assert result.exit_code == expected_exit, result.output
- return _json.loads(result.stdout)
-
- def test_gate_pause_carries_gate_block(self, tmp_path, monkeypatch):
- # CliRunner stdin is not a TTY, so the gate pauses for resume.
- payload = self._run_json(tmp_path, monkeypatch, self._WF_GATE)
- assert payload["status"] == "paused"
- assert payload["gate"] == {
- "step_id": "review",
- "message": "Approve the thing?",
- "options": ["approve", "reject"],
- "choice": None,
- }
-
- def test_completed_run_has_no_gate_block(self, tmp_path, monkeypatch):
- payload = self._run_json(tmp_path, monkeypatch, self._WF_PLAIN)
- assert payload["status"] == "completed"
- assert "gate" not in payload
-
- def test_gate_abort_carries_gate_block(self, tmp_path, monkeypatch):
- # An interactive gate the operator rejects ends the run as `aborted`
- # (on_reject defaults to abort), not `paused`. The JSON surface must
- # still carry the gate block with the recorded choice so an
- # orchestrator can see *why* the run stopped. A gate abort emits the
- # payload and then exits non-zero (aborted → exit 1), so the helper
- # is told to expect exit code 1.
- from specify_cli.workflows.steps.gate import GateStep
-
- _force_gate_stdin(monkeypatch, tty=True)
- monkeypatch.setattr(
- GateStep, "_prompt", staticmethod(lambda _msg, _opts: "reject")
- )
- payload = self._run_json(
- tmp_path, monkeypatch, self._WF_GATE, expected_exit=1
- )
- assert payload["status"] == "aborted"
- assert payload["gate"] == {
- "step_id": "review",
- "message": "Approve the thing?",
- "options": ["approve", "reject"],
- "choice": "reject",
- }
-
- def test_gate_block_emitted_only_when_run_rests_at_gate(self):
- # A run rests *on* a gate only while `paused` (awaiting a decision) or
- # `aborted` (gate rejected with on_reject: abort). current_step_id is
- # not cleared afterwards, so a `completed`/`failed` run whose last
- # executed step was a gate must NOT surface a stale gate block.
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- gate_step = {
- "type": "gate",
- "output": {
- "message": "m",
- "options": ["approve", "reject"],
- "choice": "reject",
- },
- }
-
- def _state(status):
- return SimpleNamespace(
- status=SimpleNamespace(value=status),
- current_step_id="review",
- step_results={"review": gate_step},
- )
-
- assert _gate_outcome(_state("completed")) is None
- assert _gate_outcome(_state("failed")) is None
- assert _gate_outcome(_state("paused")) is not None
- assert _gate_outcome(_state("aborted")) is not None
-
- def test_gate_block_message_coerced_to_string(self):
- # message may be a non-string YAML literal (e.g. a number); the JSON
- # surface normalises it so the emitted schema stays stable.
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- state = SimpleNamespace(
- status=SimpleNamespace(value="paused"),
- current_step_id="review",
- step_results={
- "review": {
- "type": "gate",
- "output": {"message": 12.5, "options": ["ok"], "choice": None},
- }
- },
- )
- assert _gate_outcome(state)["message"] == "12.5"
-
- def test_gate_block_options_coerced_to_strings(self):
- # options may be non-string / non-list literals in an unvalidated
- # workflow; the JSON surface always normalises them to list[str] | None
- # so the emitted schema is stable regardless of the input shape.
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- def _options_payload(options):
- state = SimpleNamespace(
- status=SimpleNamespace(value="paused"),
- current_step_id="review",
- step_results={
- "review": {
- "type": "gate",
- "output": {
- "message": "m",
- "options": options,
- "choice": None,
- },
- }
- },
- )
- return _gate_outcome(state)["options"]
-
- assert _options_payload([1, 2.5]) == ["1", "2.5"] # list
- assert _options_payload(("approve", "reject")) == ["approve", "reject"] # tuple
- assert _options_payload("approve") == ["approve"] # bare scalar, not iterated
- assert _options_payload(7) == ["7"] # numeric scalar
- assert _options_payload(None) is None # absent stays absent
-
- def test_gate_block_choice_coerced_to_string(self):
- # An unvalidated gate can record a non-string choice; the JSON
- # surface normalises it to str (and keeps None = no decision yet),
- # consistent with the message/options normalization.
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- def _choice_payload(choice):
- state = SimpleNamespace(
- status=SimpleNamespace(value="paused"),
- current_step_id="review",
- step_results={
- "review": {
- "type": "gate",
- "output": {"message": "m", "options": ["ok"], "choice": choice},
- }
- },
- )
- return _gate_outcome(state)["choice"]
-
- assert _choice_payload(None) is None # no decision yet
- assert _choice_payload("reject") == "reject" # normal string passes through
- assert _choice_payload(2) == "2" # non-string coerced
-
- def test_gate_block_detected_without_type_field(self):
- # A run paused by an older version has no persisted step `type`. The
- # gate is still detected by its unique output signature (`on_reject`),
- # so resume surfaces the gate block instead of silently dropping it.
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- state = SimpleNamespace(
- status=SimpleNamespace(value="paused"),
- current_step_id="review",
- step_results={
- "review": {
- # no "type" key — pre-dates the field being persisted
- "output": {
- "message": "Approve?",
- "options": ["approve", "reject"],
- "on_reject": "abort",
- "choice": None,
- },
- }
- },
- )
- gate = _gate_outcome(state)
- assert gate is not None
- assert gate["step_id"] == "review"
- assert gate["options"] == ["approve", "reject"]
-
- def test_non_gate_step_without_type_is_not_a_gate(self):
- # A typeless record lacking the gate signature must NOT be mistaken for
- # a gate (the fallback keys off `on_reject`, which only GateStep writes).
- from types import SimpleNamespace
- from specify_cli.workflows._commands import _gate_outcome
-
- state = SimpleNamespace(
- status=SimpleNamespace(value="paused"),
- current_step_id="run-tests",
- step_results={
- "run-tests": {"output": {"exit_code": 0, "stdout": "ok"}},
- },
- )
- assert _gate_outcome(state) is None
-
-
-class TestWorkflowAddNonStringScalars:
- """`workflow add` reports clean errors for non-string YAML scalars (#3420)."""
-
- @pytest.mark.parametrize(
- ("field_yaml", "expected"),
- [
- ('id: 123\n name: "Probe"\n version: "1.0.0"', "workflow.id"),
- ('id: "probe"\n name: "Probe"\n version: 1.0', "workflow.version"),
- ],
- )
- def test_add_reports_validation_error_not_traceback(
- self, project_dir, monkeypatch, field_yaml, expected
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- wf = project_dir / "workflow.yml"
- wf.write_text(
- "schema_version: \"1.0\"\n"
- f"workflow:\n {field_yaml}\n"
- "steps:\n - id: s1\n type: shell\n run: \"echo hi\"\n",
- encoding="utf-8",
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(wf)])
- assert result.exit_code == 1
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert expected in result.output
-
- def test_add_non_string_step_id_reports_validation_error(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- wf = project_dir / "workflow.yml"
- wf.write_text(
- "workflow:\n id: \"probe\"\n name: \"Probe\"\n version: \"1.0.0\"\n"
- "steps:\n - id: 123\n type: shell\n run: \"echo hi\"\n",
- encoding="utf-8",
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(wf)])
- assert result.exit_code == 1
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Step ID" in result.output
-
-
-class TestWorkflowCliAlignment:
- """CLI alignment with extension/preset commands (#2342)."""
-
- WORKFLOW_YAML = """
-schema_version: "1.0"
-workflow:
- id: "align-wf"
- name: "Align Workflow"
- version: "{version}"
- description: "CLI alignment test workflow"
-steps:
- - id: step-one
- type: shell
- run: "echo hello"
-"""
-
- def _write_workflow_dir(self, base, version="1.0.0"):
- d = base / "wf-src"
- d.mkdir(parents=True, exist_ok=True)
- (d / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version=version), encoding="utf-8"
- )
- return d
-
- def _archive_workflow_dir(self, source_dir, archive_path, nested=False):
- prefix = Path("align-wf-v1") if nested else Path()
- if archive_path.name.lower().endswith(".zip"):
- with zipfile.ZipFile(archive_path, "w") as archive:
- for file_path in source_dir.rglob("*"):
- if file_path.is_file():
- archive.write(
- file_path,
- prefix / file_path.relative_to(source_dir),
- )
- else:
- with tarfile.open(archive_path, "w:gz") as archive:
- for file_path in source_dir.rglob("*"):
- if file_path.is_file():
- archive.add(
- file_path,
- arcname=prefix / file_path.relative_to(source_dir),
- )
-
- def _install_dev(self, runner, app, project_dir):
- src = self._write_workflow_dir(project_dir)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
- assert result.exit_code == 0, result.output
- return src
-
- # -- add --dev -----------------------------------------------------
-
- def test_add_dev_directory_installs(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
- assert WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_local_directory_preserves_package_files(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "scripts").mkdir()
- (source / "scripts" / "helper.sh").write_text("echo helper\n")
-
- result = CliRunner().invoke(app, ["workflow", "add", str(source)])
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (installed / "scripts" / "helper.sh").read_text() == "echo helper\n"
-
- @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
- @pytest.mark.parametrize("nested", [False, True])
- def test_add_local_archive_preserves_package_files(
- self, project_dir, monkeypatch, suffix, nested
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "assets").mkdir()
- (source / "assets" / "message.txt").write_text("hello\n")
- archive_path = project_dir / f"align-wf{suffix}"
- self._archive_workflow_dir(source, archive_path, nested=nested)
-
- result = CliRunner().invoke(app, ["workflow", "add", str(archive_path)])
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (installed / "assets" / "message.txt").read_text() == "hello\n"
-
- def test_add_dev_yaml_file_installs(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- src = self._write_workflow_dir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(src / "workflow.yml"), "--dev"])
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_dev_missing_path_errors(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(project_dir / "missing"), "--dev"])
- assert result.exit_code != 0
- assert "--dev" in result.output
-
- def test_add_dev_dir_without_workflow_yml_errors(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- empty = project_dir / "empty-src"
- empty.mkdir()
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(empty), "--dev"])
- assert result.exit_code != 0
- assert "No workflow.yml found" in result.output
-
- def test_add_local_dir_without_workflow_yml_errors(self, project_dir, monkeypatch):
- """Same as the --dev case, but for the plain local-path fallback (no --dev)."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- empty = project_dir / "empty-src-[bracket]"
- empty.mkdir()
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(empty)])
- assert result.exit_code != 0
- assert "No workflow.yml found" in result.output
- assert "[bracket]" in result.output
-
- def test_add_local_dir_with_workflow_yml_directory_errors_cleanly(self, project_dir, monkeypatch):
- """Same as the --dev case, but for the plain local-path fallback (no --dev):
- a directory named workflow.yml must not reach open() and leak IsADirectoryError."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- src_dir = project_dir / "local-wf"
- (src_dir / "workflow.yml").mkdir(parents=True)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", str(src_dir)])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "No workflow.yml found" in result.output
-
- def test_add_yaml_parse_error_escapes_rich_markup(self, project_dir, monkeypatch):
- """A YAML syntax error can quote the offending line verbatim; brackets in it must not be Rich markup."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import WorkflowDefinition
-
- monkeypatch.chdir(project_dir)
- bad = project_dir / "bad.yml"
- bad.write_text("workflow:\n id: wf\n", encoding="utf-8")
- runner = CliRunner()
- with patch.object(
- WorkflowDefinition,
- "from_string",
- side_effect=ValueError('bad snippet: "New [Feature]"'),
- ):
- result = runner.invoke(app, ["workflow", "add", str(bad)])
- assert result.exit_code != 0
- assert 'bad snippet: "New [Feature]"' in result.output
-
- # -- add --from ----------------------------------------------------
-
- class _FakeResponse:
- def __init__(self, data, url="https://example.com/workflow.yml", headers=None):
- self._data = data
- self._url = url
- self._pos = 0
- self._headers = headers or {}
-
- def read(self, amt=None):
- if amt is None:
- chunk = self._data[self._pos :]
- self._pos = len(self._data)
- return chunk
- chunk = self._data[self._pos : self._pos + amt]
- self._pos += len(chunk)
- return chunk
-
- def getheader(self, name, default=None):
- return self._headers.get(name, default)
-
- def geturl(self):
- return self._url
-
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- @pytest.mark.parametrize("mode", ["dev", "local", "from"])
- def test_reinstall_preserves_disabled_state(
- self, project_dir, monkeypatch, mode
- ):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- if mode == "dev":
- result = runner.invoke(
- app, ["workflow", "add", str(src), "--dev"]
- )
- elif mode == "local":
- result = runner.invoke(app, ["workflow", "add", str(src)])
- else:
- data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(
- app,
- [
- "workflow", "add", "align-wf",
- "--from", "https://example.com/workflow.yml",
- ],
- input="y\n",
- )
-
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
-
- def test_add_from_url_rejects_oversized_content_length(self, project_dir, monkeypatch):
- """A --from download must not trust an advertised Content-Length
- alone by reading the whole body first -- it must reject a response
- that declares a size over the workflow YAML limit before reading
- the (potentially huge) body into memory at all."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- small_body = b"id: align-wf\n" # small actual body; Content-Length lies
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- small_body, url, headers={"Content-Length": "1000"}
- ),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
-
- def test_add_from_url_requires_default_deny_confirmation(
- self, project_dir, monkeypatch
- ):
- from unittest.mock import patch
-
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=AssertionError("download should not start"),
- ):
- result = CliRunner().invoke(
- app,
- [
- "workflow",
- "add",
- "align-wf",
- "--from",
- "https://example.com/workflow.yml",
- ],
- input="n\n",
- )
-
- assert result.exit_code == 0, result.output
- assert "Untrusted Source" in result.output
- assert "Cancelled" in result.output
-
- def test_add_from_url_rejects_oversized_streamed_body_without_content_length(
- self, project_dir, monkeypatch
- ):
- """A chunked/no-Content-Length response must still be capped by
- actually counting streamed bytes -- a malicious or misbehaving
- server cannot bypass the limit merely by omitting or lying about
- Content-Length."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- oversized_body = b"x" * 500 # no Content-Length header at all
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- oversized_body, url
- ),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
-
- def test_add_from_url_oversized_streamed_body_leaves_no_temp_file(
- self, project_dir, monkeypatch, tmp_path
- ):
- """A rejected --from download (oversized streamed body, no
- Content-Length) must not leave the 0-byte NamedTemporaryFile behind:
- the file is created on disk as soon as it is opened (delete=False),
- before any bytes are written, so a failure inside the size-limit
- check must still clean it up rather than merely erroring out."""
- import tempfile as tempfile_mod
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- scratch_tmp = tmp_path / "scratch-tmp"
- scratch_tmp.mkdir()
- monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
- oversized_body = b"x" * 500 # no Content-Length header at all
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- oversized_body, url
- ),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
- leaked = list(scratch_tmp.glob("*.yml"))
- assert leaked == [], f"leaked temp files: {leaked}"
-
- def test_add_from_url_interrupt_during_read_leaves_no_temp_file(
- self, project_dir, monkeypatch, tmp_path
- ):
- """A KeyboardInterrupt while streaming the response body must still
- unlink the already-created (delete=False) temp file. Unlike a
- download ``ValueError``, ``KeyboardInterrupt`` is a ``BaseException``
- and is not caught by ``except Exception`` -- only a ``BaseException``
- handler around the temp-file lifetime can clean it up."""
- import tempfile as tempfile_mod
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
-
- monkeypatch.chdir(project_dir)
- scratch_tmp = tmp_path / "scratch-tmp"
- scratch_tmp.mkdir()
- monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
-
- def _boom(*args, **kwargs):
- raise KeyboardInterrupt()
-
- monkeypatch.setattr(wf_commands, "_read_response_within_limit", _boom)
- body = b"id: align-wf\n"
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- body, url
- ),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- leaked = list(scratch_tmp.glob("*.yml"))
- assert leaked == [], f"leaked temp files: {leaked}"
-
- def test_add_from_url_oversized_content_length_leaves_no_temp_file(
- self, project_dir, monkeypatch, tmp_path
- ):
- """Same guarantee for the fail-fast Content-Length rejection path:
- it must not even leave a 0-byte temp file behind."""
- import tempfile as tempfile_mod
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- scratch_tmp = tmp_path / "scratch-tmp"
- scratch_tmp.mkdir()
- monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
- small_body = b"id: align-wf\n" # small actual body; Content-Length lies
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- small_body, url, headers={"Content-Length": "1000"}
- ),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
- leaked = list(scratch_tmp.glob("*.yml"))
- assert leaked == [], f"leaked temp files: {leaked}"
-
- def test_add_from_url_download_failure_cleanup_error_preserves_original_error(
- self, project_dir, monkeypatch, tmp_path
- ):
- """The --from download-failure branch's `tmp_path.unlink(missing_ok=
- True)` can itself raise (e.g. read-only tempdir) before the clean
- "Failed to download workflow" message is ever printed, replacing it
- with a raw unhandled OSError. A cleanup failure there must be
- guarded exactly like the later post-install finally cleanup: warn
- about the cleanup failure, then still preserve/report the original
- download error via a clean typer.Exit, never a raw traceback."""
- import tempfile as tempfile_mod
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- scratch_tmp = tmp_path / "scratch-tmp"
- scratch_tmp.mkdir()
- monkeypatch.setattr(tempfile_mod, "tempdir", str(scratch_tmp))
- oversized_body = b"x" * 500 # no Content-Length header at all
- runner = CliRunner()
-
- real_unlink = Path.unlink
-
- def unlink_boom(self_path, *args, **kwargs):
- if self_path.suffix == ".yml" and self_path.parent == scratch_tmp:
- raise OSError("cleanup denied")
- return real_unlink(self_path, *args, **kwargs)
-
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- oversized_body, url
- ),
- ), pytest.MonkeyPatch.context() as mp:
- mp.setattr(Path, "unlink", unlink_boom)
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- # Original download error remains present. Normalize whitespace so the
- # assertion is robust to Rich line-wrapping at narrow terminal widths.
- normalized_output = "".join(result.output.split())
- assert "exceedsthe100-byteworkflowsizelimit" in normalized_output
- # Cleanup failure is reported too, not silently swallowed / crashing.
- assert "cleanupdenied" in normalized_output
- assert "Warning" in result.output
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_from_url_installs(self, project_dir, monkeypatch):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).is_installed("align-wf")
-
- @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
- def test_add_from_url_installs_complete_archive_package(
- self, project_dir, monkeypatch, suffix
- ):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "assets").mkdir()
- (source / "assets" / "remote.txt").write_text("remote\n")
- archive_path = project_dir / f"remote{suffix}"
- self._archive_workflow_dir(source, archive_path)
- data = archive_path.read_bytes()
- url = f"https://example.com/align-wf{suffix}"
-
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda *_args, **_kwargs: self._FakeResponse(data, url),
- ):
- result = CliRunner().invoke(
- app,
- ["workflow", "add", "align-wf", "--from", url],
- input="y\n",
- )
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (installed / "assets" / "remote.txt").read_text() == "remote\n"
-
- @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
- def test_add_from_suffixless_url_sniffs_archive(
- self, project_dir, monkeypatch, suffix
- ):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "assets").mkdir()
- (source / "assets" / "sniffed.txt").write_text("sniffed\n")
- archive_path = project_dir / f"remote{suffix}"
- self._archive_workflow_dir(source, archive_path)
- data = archive_path.read_bytes()
- url = "https://example.com/assets/12345"
-
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda *_args, **_kwargs: self._FakeResponse(
- data,
- url,
- {"Content-Type": "application/octet-stream"},
- ),
- ):
- result = CliRunner().invoke(
- app,
- ["workflow", "add", "align-wf", "--from", url],
- input="y\n",
- )
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (installed / "assets" / "sniffed.txt").read_text() == "sniffed\n"
-
- @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
- def test_add_catalog_installs_complete_archive_package_and_sha(
- self, project_dir, monkeypatch, suffix
- ):
- import hashlib
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "assets").mkdir()
- (source / "assets" / "catalog.txt").write_text("catalog\n")
- archive_path = project_dir / f"catalog{suffix}"
- self._archive_workflow_dir(source, archive_path, nested=True)
- data = archive_path.read_bytes()
- url = f"https://example.com/align-wf{suffix}"
- info = {
- "id": "align-wf",
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": url,
- "sha256": hashlib.sha256(data).hexdigest(),
- "_install_allowed": True,
- "_catalog_name": "test",
- }
-
- with patch.object(
- WorkflowCatalog,
- "get_workflow_info",
- return_value=info,
- ), patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda *_args, **_kwargs: self._FakeResponse(data, url),
- ):
- result = CliRunner().invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (installed / "assets" / "catalog.txt").read_text() == "catalog\n"
-
- @pytest.mark.parametrize("suffix", [".zip", ".tar.gz", ".tgz"])
- def test_add_catalog_sniffs_suffixless_archive(
- self, project_dir, monkeypatch, suffix
- ):
- import hashlib
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- (source / "assets").mkdir()
- (source / "assets" / "sniffed.txt").write_text("catalog sniffed\n")
- archive_path = project_dir / f"catalog{suffix}"
- self._archive_workflow_dir(source, archive_path, nested=True)
- data = archive_path.read_bytes()
- url = "https://example.com/assets/67890"
- info = {
- "id": "align-wf",
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": url,
- "sha256": hashlib.sha256(data).hexdigest(),
- "_install_allowed": True,
- "_catalog_name": "test",
- }
-
- with patch.object(
- WorkflowCatalog,
- "get_workflow_info",
- return_value=info,
- ), patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda *_args, **_kwargs: self._FakeResponse(
- data,
- url,
- {"Content-Type": "application/octet-stream"},
- ),
- ):
- result = CliRunner().invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert (
- installed / "assets" / "sniffed.txt"
- ).read_text() == "catalog sniffed\n"
-
- def test_package_registry_failure_restores_before_failed_cleanup(
- self, project_dir, monkeypatch
- ):
- import shutil
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir, version="1.0.0")
- (source / "assets").mkdir()
- (source / "assets" / "version.txt").write_text("old\n")
- runner = CliRunner()
- first = runner.invoke(app, ["workflow", "add", str(source)])
- assert first.exit_code == 0, first.output
-
- (source / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"),
- encoding="utf-8",
- )
- (source / "assets" / "version.txt").write_text("new\n")
- real_rmtree = shutil.rmtree
-
- def fail_failed_package_cleanup(path, *args, **kwargs):
- if ".failed-" in Path(path).name:
- raise OSError("cleanup denied")
- return real_rmtree(path, *args, **kwargs)
-
- with patch.object(
- WorkflowRegistry,
- "add",
- side_effect=OSError("registry save failed"),
- ), patch(
- "shutil.rmtree",
- side_effect=fail_failed_package_cleanup,
- ):
- result = runner.invoke(app, ["workflow", "add", str(source)])
-
- assert result.exit_code == 1, result.output
- installed = project_dir / ".specify" / "workflows" / "align-wf"
- assert "1.0.0" in (installed / "workflow.yml").read_text()
- assert (installed / "assets" / "version.txt").read_text() == "old\n"
- assert "registry save failed" in result.output
- assert "cleanup denied" in result.output
-
- def test_add_from_url_temp_cleanup_failure_after_success_still_exits_zero(
- self, project_dir, monkeypatch
- ):
- """An OSError while deleting the --from download's temp file after
- _validate_and_install_local() has already committed the file and
- registry entry must not surface as an unhandled failure for an
- install that already succeeded -- it must be a warning, exit 0."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
-
- import tempfile
-
- real_unlink = Path.unlink
-
- def unlink_boom(self_path, *args, **kwargs):
- if self_path.suffix == ".yml" and self_path.parent == Path(tempfile.gettempdir()):
- raise OSError("permission denied")
- return real_unlink(self_path, *args, **kwargs)
-
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ), pytest.MonkeyPatch.context() as mp:
- mp.setattr(Path, "unlink", unlink_boom)
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
-
- assert result.exit_code == 0, result.output
- assert "Warning" in result.output
- assert "permissiondenied" in "".join(result.output.split())
- assert WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_from_url_id_mismatch_errors(self, project_dir, monkeypatch):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "other-id", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert "does not match" in result.output
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_from_empty_url_rejected_not_catalog_fallback(self, project_dir, monkeypatch):
- """--from "" must fail URL validation, not silently install from the catalog."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", "align-wf", "--from", ""])
- assert result.exit_code != 0
- assert "HTTPS" in result.output
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_from_url_non_https_redirect_escapes_rich_markup(self, project_dir, monkeypatch):
- """A redirect to a non-HTTPS IPv6 literal (legally bracketed) must not be parsed as Rich markup."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- redirected_url = "http://[2001:db8::1]/workflow.yml"
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(b"", redirected_url),
- ):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code != 0
- assert redirected_url in result.output
-
- def test_add_from_rejects_invalid_source_id_without_fetch(self, project_dir, monkeypatch):
- """--from with a non-workflow-id source (URL, path, uppercase) fails before any network fetch."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- calls: list[str] = []
-
- def _fake_open(url, timeout=None, extra_headers=None, redirect_validator=None):
- calls.append(url)
- raise AssertionError(f"network fetch attempted: {url}")
-
- runner = CliRunner()
- with patch("specify_cli.authentication.http.open_url", side_effect=_fake_open):
- for bad_source in ("https://x/y.yml", "./local.yml", "BadCase"):
- result = runner.invoke(
- app,
- ["workflow", "add", bad_source, "--from", "https://example.com/workflow.yml"],
- )
- assert result.exit_code != 0
- assert "Invalid workflow ID" in result.output
- assert calls == []
-
- # -- search --author -----------------------------------------------
-
- def test_search_author_filters(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- workflows = {
- "wf-a": {"name": "Workflow A", "version": "1.0.0", "description": "", "author": "alice"},
- "wf-b": {"name": "Workflow B", "version": "1.0.0", "description": "", "author": "bob"},
- }
- monkeypatch.setattr(
- WorkflowCatalog,
- "_get_merged_workflows",
- lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "search", "--author", "Alice"])
- assert result.exit_code == 0, result.output
- assert "wf-a" in result.output
- assert "wf-b" not in result.output
-
- def test_search_escapes_rich_markup_in_catalog_fields(self, project_dir, monkeypatch):
- """Catalog-derived name/description/tags must not be parsed as Rich markup."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- workflows = {
- "wf-a": {
- "name": "Bracket [Search]",
- "version": "1.0.0",
- "description": "desc [with] brackets",
- "tags": ["tag[1]", "tag2"],
- },
- }
- monkeypatch.setattr(
- WorkflowCatalog,
- "_get_merged_workflows",
- lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "search"])
- assert result.exit_code == 0, result.output
- assert "Bracket [Search]" in result.output
- assert "desc [with] brackets" in result.output
- assert "tag[1]" in result.output
-
- def test_search_and_info_tolerate_non_list_tags(self, project_dir, monkeypatch):
- """A scalar ``tags:`` value must not crash the search/info display.
-
- ``WorkflowCatalog.search`` guards its tag *filter* with
- ``isinstance(raw_tags, list)``, but the ``workflow search`` and
- ``workflow info`` display paths only tested truthiness before
- iterating. ``tags: 5`` is truthy and not iterable, so both raised
- ``TypeError: 'int' object is not iterable``.
- """
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- workflows = {
- "wf-a": {
- "name": "Workflow A",
- "version": "1.0.0",
- "description": "desc",
- "tags": 5,
- },
- }
- monkeypatch.setattr(
- WorkflowCatalog,
- "_get_merged_workflows",
- lambda self, force_refresh=False: {k: dict(v) for k, v in workflows.items()},
- )
- runner = CliRunner()
- searched = runner.invoke(app, ["workflow", "search"])
- info = runner.invoke(app, ["workflow", "info", "wf-a"])
-
- assert searched.exit_code == 0, searched.output
- assert "Workflow A" in searched.output
- assert "Tags:" not in searched.output
-
- assert info.exit_code == 0, info.output
- assert "Tags:" not in info.output
-
- def test_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch):
- """User-editable catalog name/url/description must not be parsed as Rich markup."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- configs = [
- {
- "name": "Bracket [Catalog]",
- "url": "https://example.com/[cat].json",
- "description": "desc [with] brackets",
- "install_allowed": True,
- },
- ]
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_catalog_configs",
- lambda self: [dict(c) for c in configs],
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "catalog", "list"])
- assert result.exit_code == 0, result.output
- assert "Bracket [Catalog]" in result.output
- assert "https://example.com/[cat].json" in result.output
- assert "desc [with] brackets" in result.output
-
- def test_step_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch):
- """User-editable step-catalog name/url/description must not be parsed as Rich markup."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import StepCatalog
-
- monkeypatch.chdir(project_dir)
- configs = [
- {
- "name": "Bracket [Step]",
- "url": "https://example.com/[step].json",
- "description": "step [with] brackets",
- "install_allowed": True,
- },
- ]
- monkeypatch.setattr(
- StepCatalog,
- "get_catalog_configs",
- lambda self: [dict(c) for c in configs],
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "step", "catalog", "list"])
- assert result.exit_code == 0, result.output
- assert "Bracket [Step]" in result.output
- assert "https://example.com/[step].json" in result.output
- assert "step [with] brackets" in result.output
-
- # -- update ----------------------------------------------------------
-
- def test_update_no_workflows_installed(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "No workflows installed" in result.output
-
- def test_update_not_installed_errors(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update", "ghost"])
- assert result.exit_code != 0
- assert "not installed" in result.output
-
- def test_update_skips_non_catalog_sources(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "re-add to update" in result.output
- # Every target was skipped — must not claim everything is up to date.
- assert "No workflows were eligible for update" in result.output
- assert "up to date!" not in result.output
-
- def test_update_skip_message_accurate_for_bundled_source(self, project_dir, monkeypatch):
- """A workflow registered with source "bundled" (e.g. the speckit
- workflow installed by `specify init`) was never installed from a
- local path or URL; the skip message must not claim otherwise."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add(
- "speckit",
- {"name": "Speckit", "version": "1.0.0", "source": "bundled"},
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "local path or URL" not in result.output
- assert "re-add to update" in result.output
-
- def test_registry_add_rolls_back_memory_on_save_failure(self, project_dir, monkeypatch):
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
-
- def boom():
- raise OSError("disk full")
-
- monkeypatch.setattr(registry, "save", boom)
- with pytest.raises(OSError):
- registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- with pytest.raises(OSError):
- registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
- assert registry.get("other-wf") is None
-
- @pytest.mark.parametrize("error_type", [TypeError, ValueError])
- def test_registry_add_rolls_back_memory_on_serialization_failure(
- self, project_dir, monkeypatch, error_type
- ):
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
-
- def boom():
- raise error_type("not JSON serializable")
-
- monkeypatch.setattr(registry, "save", boom)
- with pytest.raises(error_type):
- registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- with pytest.raises(error_type):
- registry.add("other-wf", {"version": "1.0.0", "source": "catalog"})
- assert registry.get("other-wf") is None
-
- def test_registry_add_survives_non_dict_existing_entry(self, project_dir):
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.data["workflows"]["align-wf"] = "corrupted"
- registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- def test_step_registry_add_survives_non_dict_existing_entry(self, project_dir):
- """StepRegistry.add must treat a corrupted non-dict existing entry as
- absent rather than crash on existing.get() (parity with
- WorkflowRegistry.add)."""
- from specify_cli.workflows.catalog import StepRegistry
-
- registry = StepRegistry(project_dir)
- registry.data["steps"]["my-step"] = "corrupted"
- registry.add("my-step", {"version": "1.0.0"})
- assert registry.get("my-step")["version"] == "1.0.0"
-
- @pytest.mark.parametrize(
- "contents",
- [
- "not json",
- "[]",
- '{"schema_version": "1.0"}',
- '{"schema_version": "1.0", "workflows": "broken"}',
- ],
- )
- def test_registry_load_rejects_corrupt_contents(
- self, project_dir, contents
- ):
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.workflows_dir.mkdir(parents=True, exist_ok=True)
- registry.registry_path.write_text(contents, encoding="utf-8")
-
- with pytest.raises(OSError, match="corrupt"):
- WorkflowRegistry(project_dir)
-
- assert registry.registry_path.read_text(encoding="utf-8") == contents
-
- def test_registry_save_refuses_symlinked_parent(self, project_dir, tmp_path):
- """Construction now fails closed on a symlinked .specify just like
- an unreadable registry file: a symlinked parent must never be
- silently tolerated up to save() -- it must raise immediately."""
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- outside = tmp_path / "outside-specify"
- outside.mkdir()
- specify_dir = project_dir / ".specify"
- if specify_dir.exists():
- shutil.rmtree(specify_dir)
- specify_dir.symlink_to(outside)
- with pytest.raises(OSError, match="symlink"):
- WorkflowRegistry(project_dir)
- assert not (outside / "workflows").exists()
-
- @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
- def test_registry_save_preserves_existing_file_mode(self, project_dir):
- """A registry shared as 0640/0644 must keep that mode after a save,
- not be silently replaced by mkstemp's 0600 default -- otherwise
- every add/remove locks other project users out of a previously
- shared registry file."""
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("first-wf", {"name": "First"})
- registry.registry_path.chmod(0o644)
-
- registry.add("second-wf", {"name": "Second"})
-
- mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
- assert mode == 0o644, f"expected 0644, got {oct(mode)}"
-
- @pytest.mark.skipif(not hasattr(os, "fchown"), reason="os.fchown is unavailable")
- def test_registry_save_preserves_existing_owner_group(
- self, project_dir, monkeypatch
- ):
- from specify_cli.workflows.catalog import WorkflowRegistry
- import specify_cli.workflows.catalog as catalog_mod
-
- registry = WorkflowRegistry(project_dir)
- registry.add("first-wf", {"name": "First"})
- existing = registry.registry_path.stat()
- calls: list[tuple[os.stat_result, int, int]] = []
-
- monkeypatch.setattr(
- catalog_mod.os,
- "fchown",
- lambda fd, uid, gid: calls.append((os.fstat(fd), uid, gid)),
- )
- registry.add("second-wf", {"name": "Second"})
-
- assert len(calls) == 1
- temp_stat, uid, gid = calls[0]
- assert stat.S_ISREG(temp_stat.st_mode)
- assert uid == existing.st_uid
- assert gid == existing.st_gid
-
- @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
- def test_registry_save_on_new_registry_uses_secure_default_mode(self, project_dir):
- """A brand-new registry file (no prior mode to preserve) should keep
- mkstemp's secure 0600 default rather than something more permissive."""
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("first-wf", {"name": "First"})
-
- mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
- assert mode == 0o600, f"expected 0600, got {oct(mode)}"
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_registry_save_rejects_swapped_temp_without_touching_target(
- self, project_dir, monkeypatch
- ):
- from specify_cli.workflows.catalog import WorkflowRegistry
- import specify_cli.workflows.catalog as catalog_mod
-
- registry = WorkflowRegistry(project_dir)
- registry.add("first-wf", {"name": "First"})
- registry.registry_path.chmod(0o640)
-
- victim = project_dir / "victim.txt"
- victim.write_text("untouched", encoding="utf-8")
- victim.chmod(0o600)
-
- tmp_path = None
- real_mkstemp = catalog_mod.tempfile.mkstemp
- real_dump = catalog_mod.json.dump
-
- def tracking_mkstemp(*args, **kwargs):
- nonlocal tmp_path
- fd, name = real_mkstemp(*args, **kwargs)
- tmp_path = Path(name)
- return fd, name
-
- def swap_after_dump(*args, **kwargs):
- result = real_dump(*args, **kwargs)
- assert tmp_path is not None
- tmp_path.unlink()
- tmp_path.symlink_to(victim)
- return result
-
- monkeypatch.setattr(catalog_mod.tempfile, "mkstemp", tracking_mkstemp)
- monkeypatch.setattr(catalog_mod.json, "dump", swap_after_dump)
-
- with pytest.raises(OSError):
- registry.add("second-wf", {"name": "Second"})
-
- assert victim.read_text(encoding="utf-8") == "untouched"
- if sys.platform != "win32":
- assert stat.S_IMODE(victim.stat().st_mode) == 0o600
- assert not registry.registry_path.is_symlink()
- assert WorkflowRegistry(project_dir).is_installed("first-wf")
-
- def test_add_dev_dir_with_workflow_yml_directory_errors_cleanly(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- dev_dir = project_dir / "dev-wf"
- (dev_dir / "workflow.yml").mkdir(parents=True)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", "--dev", str(dev_dir)])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "No workflow.yml found" in result.output
-
- @pytest.mark.parametrize("mode", ["dev", "local", "from_url"])
- def test_add_save_failure_leaves_no_orphan_directory(self, project_dir, monkeypatch, mode):
- """A registry.add() save failure during a fresh install must not leave
- an orphaned workflow directory on disk, and must fail with a clean
- escaped message instead of a raw OSError traceback. Shared by --dev,
- the plain local-path fallback, and --from since all three funnel
- through _validate_and_install_local's single install choke point."""
- import contextlib
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
-
- def boom(self):
- raise OSError("disk full")
-
- if mode == "from_url":
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- args = ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"]
- url_patch = patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- )
- else:
- src = self._write_workflow_dir(project_dir)
- args = ["workflow", "add", str(src)] + (["--dev"] if mode == "dev" else [])
- url_patch = contextlib.nullcontext()
-
- with url_patch, pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(
- app, args, input="y\n" if mode == "from_url" else None
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists()
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- @pytest.mark.parametrize("mode", ["dev", "catalog"])
- def test_add_non_json_description_rolls_back_transaction(
- self, project_dir, monkeypatch, mode
- ):
- import contextlib
- from unittest.mock import patch
-
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- data = self.WORKFLOW_YAML.format(version="1.0.0").replace(
- 'description: "CLI alignment test workflow"',
- "description: 2026-01-02",
- ).encode()
-
- if mode == "dev":
- source = project_dir / "dated-description"
- source.mkdir()
- (source / "workflow.yml").write_bytes(data)
- args = ["workflow", "add", str(source), "--dev"]
- download = contextlib.nullcontext()
- else:
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- args = ["workflow", "add", "align-wf"]
- download = patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- )
-
- with download:
- result = CliRunner().invoke(app, args)
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Failed to update workflow registry" in result.output
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists()
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- @pytest.mark.parametrize("mode", ["dev", "local", "from_url"])
- def test_add_fresh_install_mkstemp_failure_leaves_no_orphan_directory(
- self, project_dir, monkeypatch, mode
- ):
- """_stage_workflow_file() does mkdir(dest_dir) then mkstemp() inside
- it. For a fresh install (no prior directory), if mkdir succeeds but
- mkstemp then fails (disk full/EMFILE/quota), the freshly-created
- empty dest_dir must not be left orphaned -- it must be removed, and
- the original mkstemp error must still be reported cleanly."""
- import contextlib
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
-
- def boom(*args, **kwargs):
- raise OSError("disk full")
-
- if mode == "from_url":
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- args = ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"]
- url_patch = patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- )
- else:
- src = self._write_workflow_dir(project_dir)
- args = ["workflow", "add", str(src)] + (["--dev"] if mode == "dev" else [])
- url_patch = contextlib.nullcontext()
-
- with url_patch, pytest.MonkeyPatch.context() as mp:
- mp.setattr("tempfile.mkstemp", boom)
- result = runner.invoke(
- app, args, input="y\n" if mode == "from_url" else None
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists(), "fresh-install dest_dir left orphaned after mkstemp failure"
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_reinstall_mkstemp_failure_preserves_preexisting_directory(
- self, project_dir, monkeypatch
- ):
- """A pre-existing (reinstall) dest_dir must never be removed by the
- mkstemp-failure cleanup -- only a directory _stage_workflow_file
- itself just created."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
- installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- original_bytes = installed_yaml.read_bytes()
- original_registry_entry = WorkflowRegistry(project_dir).get("align-wf")
-
- (src / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
- )
-
- def boom(*args, **kwargs):
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr("tempfile.mkstemp", boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- assert installed_yaml.parent.is_dir()
- assert installed_yaml.read_bytes() == original_bytes
- assert WorkflowRegistry(project_dir).get("align-wf") == original_registry_entry
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- @pytest.mark.parametrize("mode", ["dev", "catalog"])
- def test_stage_write_rejects_swapped_symlink(
- self, project_dir, monkeypatch, mode
- ):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- victim = project_dir / "victim.txt"
- victim.write_text("untouched", encoding="utf-8")
-
- real_stage = _commands._stage_workflow_file
-
- def raced_stage(*args, **kwargs):
- staged = real_stage(*args, **kwargs)
- staged_path = getattr(staged, "path", staged)
- staged_path.unlink()
- staged_path.symlink_to(victim)
- return staged
-
- monkeypatch.setattr(_commands, "_stage_workflow_file", raced_stage)
-
- if mode == "dev":
- source = self._write_workflow_dir(project_dir)
- args = ["workflow", "add", str(source), "--dev"]
- else:
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- monkeypatch.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- )
- args = ["workflow", "add", "align-wf"]
-
- result = CliRunner().invoke(app, args)
-
- assert result.exit_code != 0
- assert victim.read_text(encoding="utf-8") == "untouched"
-
- def test_local_install_writes_the_same_bytes_it_validates(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- source = self._write_workflow_dir(project_dir)
- source_file = source / "workflow.yml"
- validated_content = source_file.read_text(encoding="utf-8")
- replacement_content = self.WORKFLOW_YAML.format(version="9.9.9")
-
- real_stage = _commands._stage_workflow_file
-
- def replace_source_after_validation(*args, **kwargs):
- staged = real_stage(*args, **kwargs)
- source_file.write_text(replacement_content, encoding="utf-8")
- return staged
-
- monkeypatch.setattr(
- _commands,
- "_stage_workflow_file",
- replace_source_after_validation,
- )
-
- result = CliRunner().invoke(
- app, ["workflow", "add", str(source), "--dev"]
- )
-
- assert result.exit_code == 0, result.output
- installed_file = (
- project_dir
- / ".specify"
- / "workflows"
- / "align-wf"
- / "workflow.yml"
- )
- assert installed_file.read_text(encoding="utf-8") == validated_content
- assert WorkflowRegistry(project_dir).get("align-wf")["version"] == "1.0.0"
-
- def test_add_fresh_install_staged_discard_cleanup_failure_reports_warning(
- self, project_dir, monkeypatch
- ):
- """A genuine fresh-directory rmdir failure must be reported while
- the original copy failure remains the primary error."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._write_workflow_dir(project_dir)
-
- def copy_boom(self, data):
- raise OSError("disk full")
-
- real_rmdir = Path.rmdir
-
- def rmdir_boom(path):
- if path.name == "align-wf":
- raise OSError("cleanup denied")
- return real_rmdir(path)
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(_commands._StagedWorkflowFile, "write_bytes", copy_boom)
- mp.setattr(Path, "rmdir", rmdir_boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- # Original install error remains present and primary.
- assert "disk full" in result.output
- # Cleanup failure is now reported, not silently swallowed.
- assert "cleanup denied" in result.output
- assert "Warning" in result.output
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_fresh_install_registry_rollback_cleanup_failure_reports_warning(
- self, project_dir, monkeypatch
- ):
- """A fresh-install rollback directory-removal failure must be
- reported while the registry-update error remains primary."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._write_workflow_dir(project_dir)
-
- def save_boom(self):
- raise OSError("registry disk full")
-
- real_rmdir = Path.rmdir
-
- def rmdir_boom(path):
- if path.name == "align-wf":
- raise OSError("cleanup denied")
- return real_rmdir(path)
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", save_boom)
- mp.setattr(Path, "rmdir", rmdir_boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- # Original registry-update error remains present and primary.
- assert "registry disk full" in result.output
- # Cleanup failure is now reported, not silently swallowed.
- assert "cleanup denied" in result.output
- assert "Warning" in result.output
-
- def test_add_dev_reinstall_copy_failure_leaves_prior_file_untouched(
- self, project_dir, monkeypatch
- ):
- """A staged descriptor-copy failure cannot touch the prior installed
- workflow or leave a staging file behind."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
- installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- original_bytes = installed_yaml.read_bytes()
- original_registry_entry = WorkflowRegistry(project_dir).get("align-wf")
-
- # Point --dev at a new version of the same workflow to trigger a
- # reinstall (overwrite) rather than a fresh install.
- (src / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
- )
-
- def boom(staged, data):
- # Simulate a truncating partial write followed by an OSError on
- # the reserved staging inode, mirroring disk exhaustion.
- os.ftruncate(staged.fd, 0)
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(_commands._StagedWorkflowFile, "write_bytes", boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- assert installed_yaml.read_bytes() == original_bytes
- assert WorkflowRegistry(project_dir).get("align-wf") == original_registry_entry
- # No orphaned staging file left behind in the workflow directory.
- leftovers = [p.name for p in installed_yaml.parent.iterdir() if p.name != "workflow.yml"]
- assert leftovers == []
-
- def test_add_dev_successful_reinstall_leaves_no_backup_file(
- self, project_dir, monkeypatch
- ):
- """Once registry.add() succeeds, the unique rollback backup must be
- discarded rather than left as a permanent orphan sibling."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
- workflow_dir = project_dir / ".specify" / "workflows" / "align-wf"
-
- # Reinstall (overwrite) with a new version -- a successful reinstall,
- # not a failure path.
- (src / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
- )
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code == 0, result.output
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "2.0.0"
- assert (workflow_dir / "workflow.yml").read_text(encoding="utf-8") == (
- self.WORKFLOW_YAML.format(version="2.0.0")
- )
- leftovers = [p.name for p in workflow_dir.iterdir() if p.name != "workflow.yml"]
- assert leftovers == [], f"orphan sibling(s) left behind: {leftovers}"
-
- def test_add_dev_successful_reinstall_backup_cleanup_failure_still_succeeds(
- self, project_dir, monkeypatch
- ):
- """A failure to clean up the now-unneeded backup file after a
- successful registry.add() must not turn the already-successful
- install into a reported failure: it must be a warning (exit 0),
- consistent with workflow_remove's post-commit cleanup semantics."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
-
- (src / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
- )
-
- real_unlink = Path.unlink
-
- def unlink_boom(self_path, *args, **kwargs):
- if self_path.name.endswith(".bak"):
- raise OSError("permission denied")
- return real_unlink(self_path, *args, **kwargs)
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(Path, "unlink", unlink_boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code == 0, result.output
- assert "Warning" in result.output
- assert "permissiondenied" in "".join(result.output.split())
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "2.0.0"
-
- def test_add_dev_reinstall_restore_failure_reports_warning_and_original_error(
- self, project_dir, monkeypatch
- ):
- """The prior file is now restored via an atomic rename (not a
- content rewrite) when registry.add() fails on a reinstall. If that
- restore rename itself also fails (e.g. a transient FS issue), it
- must not silently claim success or crash with a raw traceback: it
- must report a clear warning about the restore failure in addition
- to the original clean registry error."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._install_dev(runner, app, project_dir)
-
- (src / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="2.0.0"), encoding="utf-8"
- )
-
- def save_boom(self):
- raise OSError("disk full")
-
- real_replace = os.replace
- calls = {"n": 0}
-
- def replace_boom(src_path, dst_path):
- # The commit swap for a reinstall makes exactly two os.replace
- # calls (backup-aside, then staged-into-dest); let both succeed
- # and only fail the third call -- the post-registry-failure
- # restore-back rename.
- calls["n"] += 1
- if calls["n"] <= 2:
- return real_replace(src_path, dst_path)
- raise OSError("permission denied")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", save_boom)
- mp.setattr(os, "replace", replace_boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- output_compact = "".join(result.output.split())
- assert "Warning" in result.output
- assert "diskfull" in output_compact
- assert "permissiondenied" in output_compact
-
- def test_add_dev_fresh_install_into_preexisting_empty_dir_cleans_new_file(
- self, project_dir, monkeypatch
- ):
- """When the destination directory already exists but has no
- workflow.yml (e.g. an empty dir left over from elsewhere), a later
- registry.add() failure must remove the newly copied file -- the
- rollback previously did nothing in this case (existed_before=True
- with no backup bytes), leaving the new file behind -- while leaving
- the pre-existing directory itself intact."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- src = self._write_workflow_dir(project_dir)
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- dest_dir.mkdir(parents=True) # pre-existing, but empty: no workflow.yml
-
- def boom(self, *args, **kwargs):
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "add", boom)
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
-
- assert result.exit_code != 0
- assert result.output.strip() != ""
- assert dest_dir.is_dir()
- assert not (dest_dir / "workflow.yml").exists()
-
- def test_add_catalog_save_failure_leaves_no_orphan_directory(self, project_dir, monkeypatch):
- """Same guarantee as the local-install paths, but for a fresh catalog
- install: a registry.add() failure must clean up the freshly-downloaded
- directory and fail with a clean escaped message."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
-
- def boom(self):
- raise OSError("disk full")
-
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- )
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists()
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_catalog_fresh_install_mkstemp_failure_leaves_no_orphan_directory(
- self, project_dir, monkeypatch
- ):
- """Same guarantee as the local-install fresh-install case, but for a
- fresh catalog install: if _stage_workflow_file's mkdir succeeds but
- its mkstemp then fails, the freshly-created empty directory must not
- be left orphaned."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
-
- def boom(*args, **kwargs):
- raise OSError("disk full")
-
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- )
- mp.setattr("tempfile.mkstemp", boom)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists(), "fresh-install dest_dir left orphaned after mkstemp failure"
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_catalog_rejects_oversized_content_length(self, project_dir, monkeypatch):
- """Catalog installs must share the same size cap as --from: a
- response that declares an oversized Content-Length is rejected
- before its body is read into memory, and no orphan directory or
- registry mutation is left behind."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- small_body = b"id: align-wf\n" # actual body is small; header lies
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- small_body, url, headers={"Content-Length": "1000"}
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "exceedingthe100-byteworkflowsizelimit" in "".join(result.output.split())
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists()
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_catalog_rejects_oversized_streamed_body_without_content_length(
- self, project_dir, monkeypatch
- ):
- """Catalog installs must also cap actual streamed bytes when
- Content-Length is absent or understated, leaving no orphan
- directory or registry mutation behind."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands as wf_commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(wf_commands, "_MAX_WORKFLOW_YAML_BYTES", 100)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- oversized_body = b"x" * 500 # no Content-Length header at all
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- oversized_body, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "exceedsthe100-byteworkflowsizelimit" in "".join(result.output.split())
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- assert not dest_dir.exists()
- assert not WorkflowRegistry(project_dir).is_installed("align-wf")
-
- def test_add_catalog_reinstall_save_failure_restores_prior_file(self, project_dir, monkeypatch):
- """Re-adding an already-installed catalog workflow downloads the new
- version over the existing install directory. If registry.add() then
- fails to save, the prior working workflow.yml must be restored
- byte-for-byte (not left overwritten with the new download, and not
- deleted like a fresh install) and the registry must remain valid and
- still point at the original version -- the update path's caller has
- an outer backup/restore for this, but plain `workflow add` does not,
- so _install_workflow_from_catalog must handle it itself."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- source_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code == 0, result.output
-
- dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- original_data = dest_file.read_bytes()
-
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
-
- def boom(self):
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- new_data, url
- ),
- )
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- # The prior working install must survive untouched, byte-for-byte.
- assert dest_file.read_bytes() == original_data
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- def test_add_catalog_successful_reinstall_leaves_no_backup_file(
- self, project_dir, monkeypatch
- ):
- """Same orphan-backup gap as the local-install path: a successful
- catalog reinstall must not leave its unique backup behind once
- registry.add() durably succeeds."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- original_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code == 0, result.output
-
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- new_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code == 0, result.output
- workflow_dir = project_dir / ".specify" / "workflows" / "align-wf"
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "2.0.0"
- assert (workflow_dir / "workflow.yml").read_bytes() == new_data
- leftovers = [p.name for p in workflow_dir.iterdir() if p.name != "workflow.yml"]
- assert leftovers == [], f"orphan sibling(s) left behind: {leftovers}"
-
- @pytest.mark.skipif(os.name == "nt", reason="POSIX permission bits")
- def test_add_catalog_fresh_install_uses_project_file_mode(
- self, project_dir, monkeypatch
- ):
- import stat
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
-
- previous_umask = os.umask(0o022)
- try:
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- )
- result = CliRunner().invoke(
- app, ["workflow", "add", "align-wf"]
- )
- finally:
- os.umask(previous_umask)
-
- assert result.exit_code == 0, result.output
- workflow_file = (
- project_dir
- / ".specify"
- / "workflows"
- / "align-wf"
- / "workflow.yml"
- )
- assert stat.S_IMODE(workflow_file.stat().st_mode) == 0o644
-
- def test_concurrent_catalog_reinstalls_keep_file_and_registry_aligned(
- self, project_dir, monkeypatch
- ):
- import threading
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
- from specify_cli.workflows.engine import WorkflowDefinition
-
- workflows_dir = project_dir / ".specify" / "workflows"
- workflow_file = workflows_dir / "align-wf" / "workflow.yml"
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- WorkflowRegistry(project_dir).add(
- "align-wf",
- {
- "name": "Align Workflow",
- "version": "1.0.0",
- "source": "catalog",
- },
- )
-
- versions = {"install-a": "2.0.0", "install-b": "3.0.0"}
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": versions[threading.current_thread().name],
- "url": (
- "https://example.com/"
- f"{versions[threading.current_thread().name]}.yml"
- ),
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- monkeypatch.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(
- self.WORKFLOW_YAML.format(
- version=url.rsplit("/", 1)[-1].removesuffix(".yml")
- ).encode(),
- url,
- ),
- )
-
- a_committed = threading.Event()
- b_committed = threading.Event()
- a_saving = threading.Event()
- b_saved = threading.Event()
- real_commit = _commands._commit_workflow_file
- real_save = WorkflowRegistry.save
-
- def coordinated_commit(*args, **kwargs):
- backup = real_commit(*args, **kwargs)
- if threading.current_thread().name == "install-a":
- a_committed.set()
- b_committed.wait(0.5)
- else:
- b_committed.set()
- return backup
-
- def coordinated_save(registry):
- if threading.current_thread().name == "install-a":
- a_saving.set()
- b_saved.wait(0.5)
- return real_save(registry)
- assert a_saving.wait(2)
- real_save(registry)
- b_saved.set()
-
- monkeypatch.setattr(
- _commands, "_commit_workflow_file", coordinated_commit
- )
- monkeypatch.setattr(WorkflowRegistry, "save", coordinated_save)
-
- errors = []
-
- def install():
- try:
- _commands._install_workflow_from_catalog(
- project_dir,
- workflows_dir,
- "align-wf",
- )
- except BaseException as exc:
- errors.append(exc)
-
- first = threading.Thread(target=install, name="install-a")
- second = threading.Thread(target=install, name="install-b")
- first.start()
- assert a_committed.wait(2)
- second.start()
- first.join(5)
- second.join(5)
-
- assert not first.is_alive()
- assert not second.is_alive()
- assert errors == []
- file_version = WorkflowDefinition.from_yaml(workflow_file).version
- registry_version = WorkflowRegistry(project_dir).get("align-wf")[
- "version"
- ]
- assert file_version == registry_version
-
- def test_precommit_discard_preserves_concurrent_install(self, project_dir):
- from specify_cli.workflows import _commands
-
- workflow_dir = (
- project_dir / ".specify" / "workflows" / "concurrent-wf"
- )
- workflow_dir.mkdir(parents=True)
- staged_file = workflow_dir / ".workflow.yml.staged.tmp"
- staged_file.write_text("staged", encoding="utf-8")
- committed_file = workflow_dir / "workflow.yml"
- committed_file.write_text("committed", encoding="utf-8")
-
- _commands._discard_staged_workflow_file(
- staged_file, workflow_dir, existed_before=False
- )
-
- assert committed_file.read_text(encoding="utf-8") == "committed"
- assert not staged_file.exists()
-
- def test_fresh_install_rollback_preserves_concurrent_staged_file(
- self, project_dir
- ):
- """A second installer stages before taking the transaction lock, so
- the first installer's rollback must not recursively remove siblings."""
- from specify_cli.workflows import _commands
-
- workflow_dir = (
- project_dir / ".specify" / "workflows" / "concurrent-wf"
- )
- workflow_dir.mkdir(parents=True)
- committed_file = workflow_dir / "workflow.yml"
- committed_file.write_text("failed install", encoding="utf-8")
- concurrent_stage = workflow_dir / ".workflow.yml.concurrent.tmp"
- concurrent_stage.write_text("next install", encoding="utf-8")
-
- _commands._rollback_committed_workflow_file(
- committed_file,
- workflow_dir,
- existed_before=False,
- backup_file=None,
- )
-
- assert not committed_file.exists()
- assert concurrent_stage.read_text(encoding="utf-8") == "next install"
-
- def test_add_dev_registry_reopen_exit_discards_staged_file(
- self, project_dir, monkeypatch
- ):
- import typer
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
-
- monkeypatch.chdir(project_dir)
- source_dir = self._write_workflow_dir(project_dir)
- real_open_registry = _commands._open_workflow_registry
- calls = 0
-
- def fail_transaction_reopen(root):
- nonlocal calls
- calls += 1
- if calls == 2:
- raise typer.Exit(1)
- return real_open_registry(root)
-
- monkeypatch.setattr(
- _commands, "_open_workflow_registry", fail_transaction_reopen
- )
- result = CliRunner().invoke(
- app, ["workflow", "add", str(source_dir), "--dev"]
- )
-
- assert result.exit_code != 0
- assert not (
- project_dir / ".specify" / "workflows" / "align-wf"
- ).exists()
-
- def test_add_catalog_registry_reopen_exit_discards_staged_file(
- self, project_dir, monkeypatch
- ):
- import typer
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- workflows_dir = project_dir / ".specify" / "workflows"
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- monkeypatch.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- )
- monkeypatch.setattr(
- _commands,
- "_open_workflow_registry",
- lambda _root: (_ for _ in ()).throw(typer.Exit(1)),
- )
-
- with pytest.raises(typer.Exit):
- _commands._install_workflow_from_catalog(
- project_dir,
- workflows_dir,
- "align-wf",
- )
-
- assert not (workflows_dir / "align-wf").exists()
-
- def test_remove_serializes_with_concurrent_catalog_install(
- self, project_dir, monkeypatch
- ):
- import threading
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
- from specify_cli.workflows.engine import WorkflowDefinition
-
- workflows_dir = project_dir / ".specify" / "workflows"
- workflow_file = workflows_dir / "align-wf" / "workflow.yml"
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- WorkflowRegistry(project_dir).add(
- "align-wf",
- {
- "name": "Align Workflow",
- "version": "1.0.0",
- "source": "catalog",
- },
- )
- monkeypatch.setattr(
- _commands, "_require_specify_project", lambda: project_dir
- )
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- monkeypatch.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(new_data, url),
- )
-
- removal_ready = threading.Event()
- install_done = threading.Event()
- real_remove = WorkflowRegistry.remove
-
- def coordinated_remove(registry, workflow_id):
- if threading.current_thread().name == "remove":
- removal_ready.set()
- install_done.wait(0.5)
- return real_remove(registry, workflow_id)
-
- monkeypatch.setattr(WorkflowRegistry, "remove", coordinated_remove)
- errors = []
-
- def remove():
- try:
- _commands.workflow_remove("align-wf")
- except BaseException as exc:
- errors.append(exc)
-
- def install():
- try:
- _commands._install_workflow_from_catalog(
- project_dir,
- workflows_dir,
- "align-wf",
- )
- except BaseException as exc:
- errors.append(exc)
- finally:
- install_done.set()
-
- remove_thread = threading.Thread(target=remove, name="remove")
- install_thread = threading.Thread(target=install, name="install")
- remove_thread.start()
- assert removal_ready.wait(2)
- install_thread.start()
- remove_thread.join(5)
- install_thread.join(5)
-
- assert not remove_thread.is_alive()
- assert not install_thread.is_alive()
- assert errors == []
- assert WorkflowDefinition.from_yaml(workflow_file).version == "2.0.0"
- metadata = WorkflowRegistry(project_dir).get("align-wf")
- assert metadata["version"] == "2.0.0"
-
- @pytest.mark.parametrize(
- ("command_name", "initial_enabled", "expected_enabled"),
- [
- ("enable", False, True),
- ("disable", True, False),
- ],
- )
- def test_toggle_serializes_with_concurrent_catalog_update(
- self,
- project_dir,
- monkeypatch,
- command_name,
- initial_enabled,
- expected_enabled,
- ):
- import threading
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
- from specify_cli.workflows.engine import WorkflowDefinition
-
- workflows_dir = project_dir / ".specify" / "workflows"
- workflow_file = workflows_dir / "align-wf" / "workflow.yml"
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- WorkflowRegistry(project_dir).add(
- "align-wf",
- {
- "name": "Align Workflow",
- "version": "1.0.0",
- "source": "catalog",
- "enabled": initial_enabled,
- },
- )
- monkeypatch.setattr(
- _commands, "_require_specify_project", lambda: project_dir
- )
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- monkeypatch.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(new_data, url),
- )
-
- toggle_ready = threading.Event()
- update_done = threading.Event()
- real_add = WorkflowRegistry.add
-
- def coordinated_add(registry, workflow_id, metadata):
- if threading.current_thread().name == "toggle":
- toggle_ready.set()
- update_done.wait(0.5)
- return real_add(registry, workflow_id, metadata)
-
- monkeypatch.setattr(WorkflowRegistry, "add", coordinated_add)
- errors = []
-
- def toggle():
- try:
- getattr(_commands, f"workflow_{command_name}")("align-wf")
- except BaseException as exc:
- errors.append(exc)
-
- def update():
- try:
- _commands._install_workflow_from_catalog(
- project_dir,
- workflows_dir,
- "align-wf",
- )
- except BaseException as exc:
- errors.append(exc)
- finally:
- update_done.set()
-
- toggle_thread = threading.Thread(target=toggle, name="toggle")
- update_thread = threading.Thread(target=update, name="update")
- toggle_thread.start()
- assert toggle_ready.wait(2)
- update_thread.start()
- toggle_thread.join(5)
- update_thread.join(5)
-
- assert not toggle_thread.is_alive()
- assert not update_thread.is_alive()
- assert errors == []
- assert WorkflowDefinition.from_yaml(workflow_file).version == "2.0.0"
- metadata = WorkflowRegistry(project_dir).get("align-wf")
- assert metadata["version"] == "2.0.0"
- assert metadata.get("enabled", True) is expected_enabled
-
- def test_add_catalog_reinstall_restore_failure_reports_warning_and_original_error(
- self, project_dir, monkeypatch
- ):
- """Same restore-rename boundary as the local-install path: the
- prior file is restored via an atomic rename (not a content rewrite)
- when registry.add() fails on a reinstall. If that restore rename
- itself also fails, it must report a clear warning in addition to
- the original clean registry error, never crash or silently claim
- success."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- original_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code == 0, result.output
-
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
-
- def save_boom(self):
- raise OSError("disk full")
-
- real_replace = os.replace
- calls = {"n": 0}
-
- def replace_boom(src_path, dst_path):
- # The commit swap for a reinstall makes exactly two os.replace
- # calls (backup-aside, then staged-into-dest); let both succeed
- # and only fail the third call -- the post-registry-failure
- # restore-back rename.
- calls["n"] += 1
- if calls["n"] <= 2:
- return real_replace(src_path, dst_path)
- raise OSError("permission denied")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- new_data, url
- ),
- )
- mp.setattr(WorkflowRegistry, "save", save_boom)
- mp.setattr(os, "replace", replace_boom)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- output_compact = "".join(result.output.split())
- assert "Warning" in result.output
- assert "diskfull" in output_compact
- assert "permissiondenied" in output_compact
-
- def test_add_catalog_fresh_install_into_preexisting_empty_dir_cleans_new_file(
- self, project_dir, monkeypatch
- ):
- """Same rollback orphan gap as the local-install path, but for a
- fresh catalog install: a pre-existing empty destination directory
- (no workflow.yml) sets existed_before=True with no backup bytes, so
- the rollback previously did nothing on a later failure -- leaving
- the freshly downloaded workflow.yml behind. It must be removed,
- leaving the pre-existing directory itself intact."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- dest_dir = project_dir / ".specify" / "workflows" / "align-wf"
- dest_dir.mkdir(parents=True) # pre-existing, but empty: no workflow.yml
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
-
- def boom(self):
- raise OSError("disk full")
-
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- )
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.output.strip() != ""
- assert dest_dir.is_dir()
- assert not (dest_dir / "workflow.yml").exists()
-
- @pytest.mark.parametrize(
- "mode", ["redirect_rejected", "download_exception", "invalid_yaml", "id_mismatch"]
- )
- def test_add_catalog_reinstall_early_failure_restores_prior_file(
- self, project_dir, monkeypatch, mode
- ):
- """Every _install_workflow_from_catalog failure branch that runs after
- the mkdir/download step -- not just the registry.add() OSError case
- -- must route through the same existed-before/backup-aware cleanup:
- on a reinstall, a redirect rejection, a download exception, invalid
- YAML, or a workflow-id mismatch must restore the prior working
- workflow.yml rather than deleting the whole directory. One shared
- root cause (the cleanup helper), so parametrized over trigger point."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- source_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code == 0, result.output
-
- dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- original_data = dest_file.read_bytes()
-
- if mode == "redirect_rejected":
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- return self._FakeResponse(b"irrelevant", "http://evil.example.com/workflow.yml")
- elif mode == "download_exception":
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- raise OSError("network down")
- elif mode == "invalid_yaml":
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- return self._FakeResponse(b": : not valid yaml: [", url)
- else: # id_mismatch
- mismatched_yaml = self.WORKFLOW_YAML.format(version="2.0.0").replace(
- 'id: "align-wf"', 'id: "different-workflow"'
- )
-
- def fake_open_url(url, timeout=None, extra_headers=None, redirect_validator=None):
- return self._FakeResponse(mismatched_yaml.encode(), url)
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr("specify_cli.authentication.http.open_url", fake_open_url)
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- assert dest_file.read_bytes() == original_data
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- def test_download_redirect_validator_rejects_http_before_follow(self):
- import urllib.error
-
- from specify_cli.workflows._commands import _reject_insecure_download_redirect
-
- with pytest.raises(urllib.error.URLError):
- _reject_insecure_download_redirect(
- "https://example.com/wf.yml", "http://evil.example.com/wf.yml"
- )
- with pytest.raises(urllib.error.URLError):
- _reject_insecure_download_redirect(
- "https://example.com/wf.yml", "http://localhost:8000/wf.yml"
- )
- with pytest.raises(urllib.error.URLError):
- _reject_insecure_download_redirect(
- "https://example.com/wf.yml", "https://127.0.0.2/wf.yml"
- )
- # Allowed: HTTPS anywhere, or loopback HTTP that stays on loopback HTTP.
- _reject_insecure_download_redirect(
- "https://example.com/wf.yml", "https://cdn.example.com/wf.yml"
- )
- _reject_insecure_download_redirect(
- "http://localhost:7000/wf.yml", "http://localhost:8000/wf.yml"
- )
- _reject_insecure_download_redirect(
- "http://127.0.0.1/source.yml", "http://127.0.0.1/wf.yml"
- )
- _reject_insecure_download_redirect(
- "http://127.0.0.2/source.yml", "http://127.255.255.254/wf.yml"
- )
-
- def test_add_from_url_passes_redirect_validator(self, project_dir, monkeypatch):
- from unittest.mock import patch
-
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- seen: dict[str, object] = {}
-
- def fake_open(url, timeout=None, extra_headers=None, redirect_validator=None):
- seen["validator"] = redirect_validator
- return self._FakeResponse(data, url)
-
- runner = CliRunner()
- with patch("specify_cli.authentication.http.open_url", side_effect=fake_open):
- result = runner.invoke(
- app,
- ["workflow", "add", "align-wf", "--from", "https://example.com/workflow.yml"],
- input="y\n",
- )
- assert result.exit_code == 0, result.output
- from specify_cli.workflows._commands import _reject_insecure_download_redirect
-
- assert seen["validator"] is _reject_insecure_download_redirect
-
- @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
- def test_registry_save_failure_preserves_file_on_disk(self, project_dir, monkeypatch):
- """A failed dump must not truncate the persisted registry, and must
- not alter its on-disk mode either -- the chmod-to-match-existing-mode
- step operates on the temp file, never the target, so a failed save
- (which never reaches os.replace) cannot touch the original's mode."""
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
- registry.registry_path.chmod(0o644)
-
- import specify_cli.workflows.catalog as catalog_mod
-
- def boom(*args, **kwargs):
- raise OSError("disk full")
-
- monkeypatch.setattr(catalog_mod.json, "dump", boom)
- with pytest.raises(OSError):
- registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
- monkeypatch.undo()
-
- fresh = WorkflowRegistry(project_dir)
- assert fresh.get("align-wf")["version"] == "1.0.0"
- assert stat.S_IMODE(registry.registry_path.stat().st_mode) == 0o644
- assert not list(registry.workflows_dir.glob("*.tmp"))
-
- def test_update_mixed_targets_does_not_claim_all_up_to_date(self, project_dir, monkeypatch):
- """Skipped targets must not be presented as verified up to date."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir) # local source → skipped
- WorkflowRegistry(project_dir).add("catalog-wf", {
- "name": "Catalog Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- })
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- },
- )
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "All workflows are up to date!" not in result.output
- assert "All checked workflows are up to date" in result.output
- assert "skipped" in result.output
-
- def test_run_refuses_falsy_non_bool_enabled(self, project_dir, monkeypatch):
- """A falsy non-bool "enabled" (0) shows as disabled in list — run must agree."""
- import json as json_mod
-
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- registry = WorkflowRegistry(project_dir)
- registry.data["workflows"]["align-wf"]["enabled"] = 0
- registry.registry_path.write_text(json_mod.dumps(registry.data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "run", "align-wf"])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- def test_update_installs_newer_catalog_version(self, project_dir, monkeypatch):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "CLI alignment test workflow",
- "source": "catalog",
- "catalog_name": "test-catalog",
- "url": "https://example.com/workflow.yml",
- })
- wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
- wf_dir.mkdir(parents=True)
- (wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert result.exit_code == 0, result.output
- assert "1.0.0" in result.output and "2.0.0" in result.output
- meta = WorkflowRegistry(project_dir).get("align-wf")
- assert meta["version"] == "2.0.0"
- assert "2.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
-
- def test_update_downloaded_invalid_yaml_escapes_rich_markup(self, project_dir, monkeypatch):
- """A malformed downloaded workflow can quote the offending line verbatim; escape it before printing."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
- from specify_cli.workflows.engine import WorkflowDefinition
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "CLI alignment test workflow",
- "source": "catalog",
- "catalog_name": "test-catalog",
- "url": "https://example.com/workflow.yml",
- })
- wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
- wf_dir.mkdir(parents=True)
- (wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(b"", url),
- ), patch.object(
- WorkflowDefinition,
- "from_string",
- side_effect=ValueError('bad snippet: "New [Feature]"'),
- ):
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert 'bad snippet: "New [Feature]"' in result.output
- assert "Failed to update" in result.output
- # The previously installed workflow must survive a failed update.
- assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
-
- def test_update_malformed_catalog_url_fails_cleanly(self, project_dir, monkeypatch):
- """An unparseable catalog URL (unbalanced IPv6 literal) must not abort the whole update."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "CLI alignment test workflow",
- "source": "catalog",
- "catalog_name": "test-catalog",
- "url": "https://[::1/workflow.yml",
- })
- wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
- wf_dir.mkdir(parents=True)
- (wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://[::1/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert "malformed install URL" in result.output
- assert "Failed to update" in result.output
- # The previously installed workflow must survive.
- assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
-
- def test_add_non_string_catalog_url_fails_cleanly(self, project_dir, monkeypatch):
- """A truthy non-string catalog URL must hit the clean error path, not AttributeError."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": 123,
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "malformed install URL" in result.output
-
- def test_enable_failed_save_leaves_workflow_disabled(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- def boom(self):
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(app, ["workflow", "enable", "align-wf"])
- assert result.exit_code != 0
-
- assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
- result = runner.invoke(app, ["workflow", "enable", "align-wf"])
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is True
-
- @pytest.mark.parametrize("command", ["enable", "disable"])
- def test_enable_disable_save_failure_gives_clean_output(
- self, project_dir, monkeypatch, command
- ):
- """A save() failure in enable/disable must produce a clean escaped CLI
- error, not surface the raw OSError as an unhandled exception. Shared
- root behavior: both call registry.add() with a fresh mapping and must
- catch its deliberate OSError the same way."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
- # disable starts from the enabled default; enable needs a prior disable.
- starting_enabled = command == "disable"
- if command == "enable":
- pre = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert pre.exit_code == 0, pre.output
-
- def boom(self):
- raise OSError("disk full")
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(WorkflowRegistry, "save", boom)
- result = runner.invoke(app, ["workflow", command, "align-wf"])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert result.output.strip() != ""
- assert (
- WorkflowRegistry(project_dir).get("align-wf").get("enabled", True)
- is starting_enabled
- )
-
- def test_update_rejects_version_mismatch_from_stale_url(self, project_dir, monkeypatch):
- """A URL serving a different version than the catalog advertised must fail the update."""
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- WorkflowRegistry(project_dir).add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "CLI alignment test workflow",
- "source": "catalog",
- "catalog_name": "test-catalog",
- "url": "https://example.com/workflow.yml",
- })
- wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
- wf_dir.mkdir(parents=True)
- (wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- # The URL still serves the old 1.0.0 payload.
- data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert "does not match the catalog version" in result.output
- assert "Failed to update" in result.output
- meta = WorkflowRegistry(project_dir).get("align-wf")
- assert meta["version"] == "1.0.0"
- assert "1.0.0" in (wf_dir / "workflow.yml").read_text(encoding="utf-8")
-
- def test_update_preserves_disabled_state(self, project_dir, monkeypatch):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- WorkflowRegistry(project_dir).add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- "enabled": False,
- })
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- },
- )
- data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- runner = CliRunner()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert result.exit_code == 0, result.output
- meta = WorkflowRegistry(project_dir).get("align-wf")
- assert meta["version"] == "2.0.0"
- assert meta["enabled"] is False
-
- @pytest.mark.skipif(os.name == "nt", reason="POSIX permission bits")
- def test_update_preserves_workflow_file_mode(self, project_dir, monkeypatch):
- import stat
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- WorkflowRegistry(project_dir).add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- })
- workflow_file = (
- project_dir
- / ".specify"
- / "workflows"
- / "align-wf"
- / "workflow.yml"
- )
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- workflow_file.chmod(0o640)
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- },
- )
- data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(data, url),
- ):
- result = CliRunner().invoke(
- app, ["workflow", "update"], input="y\n"
- )
-
- assert result.exit_code == 0, result.output
- assert stat.S_IMODE(workflow_file.stat().st_mode) == 0o640
-
- def test_update_skips_corrupted_registry_entry(self, project_dir, monkeypatch):
- import json
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.parent.mkdir(parents=True, exist_ok=True)
- registry_path.write_text(
- json.dumps({"schema_version": "1.0", "workflows": {"broken": "not-a-dict"}}),
- encoding="utf-8",
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "corrupted" in result.output
-
- def test_list_skips_corrupted_registry_entry(self, project_dir, monkeypatch):
- import json
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.parent.mkdir(parents=True, exist_ok=True)
- registry_path.write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- "broken": "not-a-dict",
- "ok": {"name": "OK Workflow", "version": "1.0.0"},
- },
- }
- ),
- encoding="utf-8",
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "list"])
- assert result.exit_code == 0, result.output
- assert "corrupted" in result.output
- assert "OK Workflow" in result.output
-
- def test_list_unreadable_registry_fails_closed_with_clean_error(
- self, project_dir, monkeypatch
- ):
- """An unreadable registry file must produce a clean CLI error, not a
- raw traceback and not a silent "nothing installed" list -- the latter
- is exactly the fail-open state a caller could otherwise mistake for
- "safe to (re)install", overwriting real files. Covers the read/query
- boundary fix required at every WorkflowRegistry call site."""
- import builtins
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- registry_path = WorkflowRegistry(project_dir).registry_path.resolve()
- real_open = builtins.open
-
- def _raising_open(file, mode="r", *args, **kwargs):
- if Path(file).resolve() == registry_path and "r" in mode:
- raise OSError("simulated read failure")
- return real_open(file, mode, *args, **kwargs)
-
- monkeypatch.setattr(builtins, "open", _raising_open)
- result = runner.invoke(app, ["workflow", "list"])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Error" in result.output
-
- def test_list_escapes_rich_markup_in_registry_fields(self, project_dir, monkeypatch):
- """User-editable name/description/id fields must not be parsed as Rich markup."""
- import json
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.parent.mkdir(parents=True, exist_ok=True)
- registry_path.write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- "ok": {
- "name": "Bracket [Test]",
- "version": "1.0.0",
- "description": "desc [with] brackets",
- },
- },
- }
- ),
- encoding="utf-8",
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "list"])
- assert result.exit_code == 0, result.output
- assert "Bracket [Test]" in result.output
- assert "desc [with] brackets" in result.output
-
- def test_update_reports_unsafe_registry_id_per_workflow(self, project_dir, monkeypatch):
- """An unsafe workflow id in the registry must fail that one entry, not abort the whole update."""
- import json
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry, WorkflowCatalog
-
- monkeypatch.chdir(project_dir)
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.parent.mkdir(parents=True, exist_ok=True)
- registry_path.write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- "../evil": {
- "name": "Bad",
- "version": "0.0.1",
- "source": "catalog",
- "url": "https://example.com/evil.yml",
- },
- },
- }
- ),
- encoding="utf-8",
- )
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {"version": "9.9.9", "url": "https://example.com/evil.yml", "_install_allowed": True},
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert result.exit_code != 0
- assert "Failed to update" in result.output
-
- def test_update_registry_save_failure_restores_prior_file_without_redundant_write(
- self, project_dir, monkeypatch
- ):
- """A registry.add() save failure during `workflow update` must be
- fully restored by _install_workflow_from_catalog's own atomic
- rollback (rename-based, not a byte-level rewrite). The outer
- workflow_update loop must not perform any redundant write of its
- own onto the destination file -- that write happened only after
- typer.Exit already unwound, could itself fail/truncate the safely
- preserved file, and is provably unnecessary here since the inner
- transaction already restored it via rename."""
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- source_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- runner = CliRunner()
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- source_data, url
- ),
- )
- result = runner.invoke(app, ["workflow", "add", "align-wf"])
- assert result.exit_code == 0, result.output
-
- dest_file = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- original_data = dest_file.read_bytes()
-
- new_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
-
- def boom_save(self):
- raise OSError("disk full")
-
- dest_writes: list[bytes] = []
- real_write_bytes = Path.write_bytes
- resolved_dest_file = dest_file.resolve()
-
- def tracking_write_bytes(self_path, data, *args, **kwargs):
- if self_path.resolve() == resolved_dest_file:
- dest_writes.append(data)
- return real_write_bytes(self_path, data, *args, **kwargs)
-
- with pytest.MonkeyPatch.context() as mp:
- mp.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- mp.setattr(
- "specify_cli.authentication.http.open_url",
- lambda url, timeout=None, extra_headers=None, redirect_validator=None: self._FakeResponse(
- new_data, url
- ),
- )
- mp.setattr(WorkflowRegistry, "save", boom_save)
- mp.setattr(Path, "write_bytes", tracking_write_bytes)
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
-
- assert result.exit_code != 0
- assert "Failed to update" in result.output
- # No redundant/second write of the destination file was attempted --
- # the inner atomic commit/rollback (rename-based) is the only thing
- # that ever touches it.
- assert dest_writes == []
- assert dest_file.read_bytes() == original_data
- registry = WorkflowRegistry(project_dir)
- assert registry.is_installed("align-wf")
- assert registry.get("align-wf")["version"] == "1.0.0"
-
- def test_update_non_json_description_restores_prior_file_and_registry(
- self, project_dir, monkeypatch
- ):
- from unittest.mock import patch
-
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add(
- "align-wf",
- {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- },
- )
- workflow_file = (
- project_dir
- / ".specify"
- / "workflows"
- / "align-wf"
- / "workflow.yml"
- )
- workflow_file.parent.mkdir(parents=True)
- original_data = self.WORKFLOW_YAML.format(version="1.0.0").encode()
- workflow_file.write_bytes(original_data)
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
- invalid_data = self.WORKFLOW_YAML.format(version="2.0.0").replace(
- 'description: "CLI alignment test workflow"',
- "description: 2026-01-02",
- ).encode()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(invalid_data, url),
- ):
- result = CliRunner().invoke(
- app, ["workflow", "update", "align-wf"], input="y\n"
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Failed to update workflow registry" in result.output
- assert workflow_file.read_bytes() == original_data
- current = WorkflowRegistry(project_dir).get("align-wf")
- assert current["version"] == "1.0.0"
- leftovers = [
- path.name
- for path in workflow_file.parent.iterdir()
- if path.name != "workflow.yml"
- ]
- assert leftovers == []
-
- def test_commit_failure_reports_unrestored_backup_location(
- self, tmp_path, monkeypatch
- ):
- from specify_cli.workflows import _commands
-
- dest_dir = tmp_path / "align-wf"
- dest_dir.mkdir()
- dest_file = dest_dir / "workflow.yml"
- staged_file = dest_dir / ".workflow.yml.staged"
- dest_file.write_text("original", encoding="utf-8")
- staged_file.write_text("replacement", encoding="utf-8")
-
- real_replace = os.replace
- calls = 0
- backup_file = None
-
- def fail_commit_and_restore(src, dst):
- nonlocal backup_file, calls
- calls += 1
- if calls == 1:
- backup_file = Path(dst)
- return real_replace(src, dst)
- if calls == 2:
- raise OSError("commit denied")
- raise OSError("restore denied")
-
- monkeypatch.setattr(os, "replace", fail_commit_and_restore)
- with pytest.raises(OSError) as exc_info:
- _commands._commit_workflow_file(
- staged_file, dest_file, existed_before=True
- )
-
- message = str(exc_info.value)
- assert "commit denied" in message
- assert "restore denied" in message
- assert backup_file is not None
- assert str(backup_file) in message
- assert not dest_file.exists()
- assert backup_file.read_text(encoding="utf-8") == "original"
-
- def test_commit_keyboard_interrupt_restores_prior_file(
- self, tmp_path, monkeypatch
- ):
- from specify_cli.workflows import _commands
-
- dest_dir = tmp_path / "align-wf"
- dest_dir.mkdir()
- dest_file = dest_dir / "workflow.yml"
- staged_file = dest_dir / ".workflow.yml.staged"
- dest_file.write_text("original", encoding="utf-8")
- staged_file.write_text("replacement", encoding="utf-8")
-
- real_replace = os.replace
- calls = 0
-
- def interrupt_commit(src, dst):
- nonlocal calls
- calls += 1
- if calls == 2:
- raise KeyboardInterrupt
- return real_replace(src, dst)
-
- monkeypatch.setattr(os, "replace", interrupt_commit)
- with pytest.raises(KeyboardInterrupt):
- _commands._commit_workflow_file(
- staged_file, dest_file, existed_before=True
- )
-
- assert dest_file.read_text(encoding="utf-8") == "original"
- assert staged_file.read_text(encoding="utf-8") == "replacement"
- assert list(dest_dir.glob("*.bak")) == []
-
- def test_commit_interrupt_after_first_rename_restores_prior_file(
- self, tmp_path, monkeypatch
- ):
- from specify_cli.workflows import _commands
-
- dest_dir = tmp_path / "align-wf"
- dest_dir.mkdir()
- dest_file = dest_dir / "workflow.yml"
- staged_file = dest_dir / ".workflow.yml.staged"
- dest_file.write_text("original", encoding="utf-8")
- staged_file.write_text("replacement", encoding="utf-8")
-
- real_replace = os.replace
- calls = 0
-
- def interrupt_after_replace(src, dst):
- nonlocal calls
- calls += 1
- result = real_replace(src, dst)
- if calls == 1:
- raise KeyboardInterrupt
- return result
-
- monkeypatch.setattr(os, "replace", interrupt_after_replace)
- with pytest.raises(KeyboardInterrupt):
- _commands._commit_workflow_file(
- staged_file, dest_file, existed_before=True
- )
-
- assert dest_file.read_text(encoding="utf-8") == "original"
- assert staged_file.read_text(encoding="utf-8") == "replacement"
- assert list(dest_dir.glob("*.bak")) == []
-
- def test_commit_uses_unique_backup_without_overwriting_existing_sibling(
- self, tmp_path
- ):
- from specify_cli.workflows import _commands
-
- dest_dir = tmp_path / "align-wf"
- dest_dir.mkdir()
- dest_file = dest_dir / "workflow.yml"
- staged_file = dest_dir / ".workflow.yml.staged"
- fixed_backup = dest_dir / "workflow.yml.bak"
- dest_file.write_text("original", encoding="utf-8")
- staged_file.write_text("replacement", encoding="utf-8")
- fixed_backup.write_text("diagnostic copy", encoding="utf-8")
-
- backup_file = _commands._commit_workflow_file(
- staged_file, dest_file, existed_before=True
- )
-
- assert backup_file is not None
- assert backup_file != fixed_backup
- assert backup_file.read_text(encoding="utf-8") == "original"
- assert fixed_backup.read_text(encoding="utf-8") == "diagnostic copy"
- assert dest_file.read_text(encoding="utf-8") == "replacement"
-
- @pytest.mark.parametrize(
- ("replacement_source", "replacement_version"),
- [("local", "1.0.0"), ("catalog", "1.5.0")],
- )
- def test_update_rechecks_registry_after_confirmation(
- self, project_dir, monkeypatch, replacement_source, replacement_version
- ):
- from unittest.mock import patch
-
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows import _commands
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry = WorkflowRegistry(project_dir)
- registry.add(
- "align-wf",
- {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- },
- )
- workflow_file = (
- project_dir
- / ".specify"
- / "workflows"
- / "align-wf"
- / "workflow.yml"
- )
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- replacement_data = self.WORKFLOW_YAML.format(
- version=replacement_version
- ).replace(
- 'description: "CLI alignment test workflow"',
- 'description: "concurrent replacement"',
- ).encode()
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "name": "Align Workflow",
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- "_catalog_name": "test-catalog",
- },
- )
-
- def replace_while_confirming(*args, **kwargs):
- WorkflowRegistry(project_dir).add(
- "align-wf",
- {
- "name": "Concurrent replacement",
- "version": replacement_version,
- "description": "",
- "source": replacement_source,
- },
- )
- workflow_file.write_bytes(replacement_data)
- return True
-
- monkeypatch.setattr(_commands.typer, "confirm", replace_while_confirming)
- catalog_data = self.WORKFLOW_YAML.format(version="2.0.0").encode()
- with patch(
- "specify_cli.authentication.http.open_url",
- side_effect=lambda url, timeout=None, extra_headers=None,
- redirect_validator=None: self._FakeResponse(catalog_data, url),
- ):
- result = CliRunner().invoke(app, ["workflow", "update", "align-wf"])
-
- assert result.exit_code != 0
- assert "changed during update" in result.output
- assert workflow_file.read_bytes() == replacement_data
- current = WorkflowRegistry(project_dir).get("align-wf")
- assert current["source"] == replacement_source
- assert current["version"] == replacement_version
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_resume_rejects_symlinked_cross_project_owner_root(
- self, project_dir, tmp_path
- ):
- from specify_cli.workflows import _commands
-
- real_owner = tmp_path / "real-owner"
- real_owner.mkdir()
- owner_link = tmp_path / "owner-link"
- owner_link.symlink_to(real_owner, target_is_directory=True)
-
- with pytest.raises(ValueError, match="unavailable"):
- _commands._resolve_run_owner_root(str(owner_link), project_dir)
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_resume_rejects_cross_project_owner_with_symlinked_ancestor(
- self, project_dir, tmp_path
- ):
- from specify_cli.workflows import _commands
-
- real_parent = tmp_path / "real-parent"
- owner = real_parent / "owner"
- owner.mkdir(parents=True)
- parent_link = tmp_path / "parent-link"
- parent_link.symlink_to(real_parent, target_is_directory=True)
-
- with pytest.raises(ValueError, match="unavailable"):
- _commands._resolve_run_owner_root(
- str(parent_link / "owner"), project_dir
- )
-
- def test_enable_disable_corrupted_registry_entry_errors(self, project_dir, monkeypatch):
- import json
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.parent.mkdir(parents=True, exist_ok=True)
- registry_path.write_text(
- json.dumps({"schema_version": "1.0", "workflows": {"broken": "not-a-dict"}}),
- encoding="utf-8",
- )
- runner = CliRunner()
- for cmd in ("enable", "disable"):
- result = runner.invoke(app, ["workflow", cmd, "broken"])
- assert result.exit_code != 0
- assert "corrupted" in result.output
-
- def test_update_up_to_date_reports_and_exits_zero(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- WorkflowRegistry(project_dir).add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- })
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "version": "1.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- },
- )
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "update"])
- assert result.exit_code == 0, result.output
- assert "Up to date" in result.output
- assert "All workflows are up to date!" in result.output
-
- def test_update_restores_backup_on_failed_download(self, project_dir, monkeypatch):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- WorkflowRegistry(project_dir).add("align-wf", {
- "name": "Align Workflow",
- "version": "1.0.0",
- "description": "",
- "source": "catalog",
- "url": "https://example.com/workflow.yml",
- })
- wf_dir = project_dir / ".specify" / "workflows" / "align-wf"
- wf_dir.mkdir(parents=True)
- original = self.WORKFLOW_YAML.format(version="1.0.0")
- (wf_dir / "workflow.yml").write_text(original, encoding="utf-8")
-
- monkeypatch.setattr(
- WorkflowCatalog,
- "get_workflow_info",
- lambda self, wid: {
- "id": wid,
- "version": "2.0.0",
- "url": "https://example.com/workflow.yml",
- "_install_allowed": True,
- },
- )
-
- def boom(url, timeout=None, extra_headers=None, redirect_validator=None):
- raise OSError("network down")
-
- runner = CliRunner()
- with patch("specify_cli.authentication.http.open_url", side_effect=boom):
- result = runner.invoke(app, ["workflow", "update"], input="y\n")
- assert result.exit_code != 0
- assert "Failed to update" in result.output
- # Working copy and registry version are untouched
- assert (wf_dir / "workflow.yml").read_text(encoding="utf-8") == original
- assert WorkflowRegistry(project_dir).get("align-wf")["version"] == "1.0.0"
-
- # -- enable / disable ------------------------------------------------
-
- def test_disable_blocks_run_enable_restores(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is False
-
- result = runner.invoke(app, ["workflow", "run", "align-wf"])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- result = runner.invoke(app, ["workflow", "enable", "align-wf"])
- assert result.exit_code == 0, result.output
- assert WorkflowRegistry(project_dir).get("align-wf")["enabled"] is True
-
- result = runner.invoke(app, ["workflow", "run", "align-wf"])
- assert result.exit_code == 0, result.output
-
- def test_run_rejects_corrupted_registry_entry(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- registry = WorkflowRegistry(project_dir)
- registry.data["workflows"]["align-wf"] = "corrupted"
- registry.save()
-
- result = runner.invoke(app, ["workflow", "run", "align-wf"])
- assert result.exit_code != 0
- assert "corrupted" in result.output
-
- def test_run_rejects_corrupt_registry_file(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- registry_path = WorkflowRegistry(project_dir).registry_path
- registry_path.write_text("not json", encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "run", "align-wf"])
-
- assert result.exit_code != 0
- assert "registry" in result.output.lower()
- assert "corrupt" in result.output.lower()
-
- def test_disable_blocks_case_variant_installed_path(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- case_variant = (
- project_dir
- / ".SPECIFY"
- / "WORKFLOWS"
- / "ALIGN-WF"
- / "workflow.yml"
- )
- if not case_variant.is_file():
- pytest.skip("filesystem is case-sensitive")
-
- result = runner.invoke(
- app, ["workflow", "run", str(case_variant)]
- )
-
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- def test_disable_blocks_run_via_path_equivalent_id(self, project_dir, monkeypatch):
- """Path-equivalent and newline IDs must not dodge the registry lookup."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- for spelling in ("align-wf/", "align-wf/.", "align-wf\n"):
- result = runner.invoke(app, ["workflow", "run", spelling])
- assert result.exit_code != 0, spelling
- assert "Invalid workflow ID" in result.output, spelling
-
- # Direct path to the installed workflow's own YAML must also refuse.
- installed_yaml = ".specify/workflows/align-wf/workflow.yml"
- assert (project_dir / installed_yaml).is_file()
- result = runner.invoke(app, ["workflow", "run", installed_yaml])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- # Same guard must hold when invoked from outside the project.
- outside = project_dir.parent / "outside-cwd"
- outside.mkdir(exist_ok=True)
- monkeypatch.chdir(outside)
- result = runner.invoke(
- app, ["workflow", "run", str(project_dir / installed_yaml)]
- )
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_disable_blocks_run_when_installed_yaml_is_symlinked(
- self, project_dir, monkeypatch
- ):
- """A disabled workflow's own workflow.yml being replaced with a symlink
- must not bypass the disabled check. Resolving the path before mapping
- it back to its registry owner would follow the symlink out of
- .specify/workflows, fail to find an owner, and let engine.load_workflow
- run the original symlink target anyway -- ownership must be
- determined from the normalized *lexical* path (not resolve()), and a
- symlinked path component in the installed tree must be refused."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- installed_yaml = project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- external_target = project_dir / "external-workflow.yml"
- external_target.write_text(
- self.WORKFLOW_YAML.format(version="9.9.9"), encoding="utf-8"
- )
- installed_yaml.unlink()
- installed_yaml.symlink_to(external_target)
-
- result = runner.invoke(app, ["workflow", "run", str(installed_yaml)])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "disabled" in result.output or "symlink" in result.output.lower()
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_alias_rejects_symlinked_workflow_storage_before_resolve(
- self, project_dir, temp_dir
- ):
- import shutil
- import typer
- from specify_cli.workflows import _commands
-
- specify_dir = project_dir / ".specify"
- shutil.rmtree(specify_dir)
- redirected = temp_dir / "redirected-storage"
- workflow_file = redirected / "workflows" / "evil" / "workflow.yml"
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- specify_dir.symlink_to(redirected, target_is_directory=True)
- alias = temp_dir / "workflow-alias.yml"
- alias.symlink_to(
- project_dir
- / ".specify"
- / "workflows"
- / "evil"
- / "workflow.yml"
- )
-
- with pytest.raises(typer.Exit):
- _commands._resolve_installed_workflow_ownership(
- alias, _commands.err_console
- )
+ registry = WorkflowRegistry(project_dir)
+ registry.add("first-wf", {"name": "First"})
+ existing = registry.registry_path.stat()
+ calls: list[tuple[os.stat_result, int, int]] = []
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_run_refuses_symlinked_specify_dir_hiding_disabled_workflow(
- self, temp_dir, monkeypatch
- ):
- """A victim project's own .specify directory being a symlink to an
- attacker-controlled tree must not bypass the disabled-workflow guard.
- _reject_unsafe_workflow_storage only checks the *cwd's* project root
- (unrelated here); the id/leaf symlink-component loop only checks
- components from the id directory onward, missing .specify/
- .specify/workflows themselves. The ownership check must reject an
- unsafe .specify/.specify-workflows for the actual path-derived
- registry root before ever consulting the registry -- it must not
- rely on WorkflowRegistry's own symlinked-parent handling, which
- raises a generic OSError; the ownership guard should surface the
- specific unsafe-storage error before registry construction."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- victim = temp_dir / "victim"
- victim.mkdir()
- attacker_real = temp_dir / "attacker-real"
- (attacker_real / "workflows" / "evil").mkdir(parents=True)
- (attacker_real / "workflows" / "evil" / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- (attacker_real / "workflows" / "workflow-registry.json").write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- "evil": {
- "name": "Evil",
- "version": "1.0.0",
- "source": "dev",
- "enabled": False,
- }
- },
- }
- ),
- encoding="utf-8",
+ monkeypatch.setattr(
+ catalog_mod.os,
+ "fchown",
+ lambda fd, uid, gid: calls.append((os.fstat(fd), uid, gid)),
)
- (victim / ".specify").symlink_to(attacker_real)
+ registry.add("second-wf", {"name": "Second"})
- unrelated_cwd = temp_dir / "unrelated-cwd"
- unrelated_cwd.mkdir()
- monkeypatch.chdir(unrelated_cwd)
+ assert len(calls) == 1
+ temp_stat, uid, gid = calls[0]
+ assert stat.S_ISREG(temp_stat.st_mode)
+ assert uid == existing.st_uid
+ assert gid == existing.st_gid
- runner = CliRunner()
- target = victim / ".specify" / "workflows" / "evil" / "workflow.yml"
- result = runner.invoke(app, ["workflow", "run", str(target)])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "symlink" in result.output.lower()
+ @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
+ def test_registry_save_on_new_registry_uses_secure_default_mode(self, project_dir):
+ """A brand-new registry file (no prior mode to preserve) should keep
+ mkstemp's secure 0600 default rather than something more permissive."""
+ from specify_cli.workflows.catalog import WorkflowRegistry
- def test_run_nested_installed_paths_uses_nearest_owner(
- self, temp_dir, monkeypatch
- ):
- """A direct workflow.yml path whose lexical segments contain
- .specify/workflows more than once (an unrelated nested project
- happens to live beneath an outer installed workflow's own
- directory tree, reusing the same segment names) must be attributed
- to its *nearest* (innermost) owning project/ID -- scanning from the
- start of the path and stopping at the first match would pick the
- outer project and the wrong workflow ID, gating the run on an
- unrelated workflow's disabled state instead of the real owner's."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- def _write_registry(workflows_dir, workflow_id, enabled):
- workflows_dir.mkdir(parents=True, exist_ok=True)
- (workflows_dir / "workflow-registry.json").write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- workflow_id: {
- "name": workflow_id,
- "version": "1.0.0",
- "source": "dev",
- "enabled": enabled,
- }
- },
- }
- ),
- encoding="utf-8",
- )
+ registry = WorkflowRegistry(project_dir)
+ registry.add("first-wf", {"name": "First"})
- outer_workflows = temp_dir / "outer-proj" / ".specify" / "workflows"
- outer_wf_dir = outer_workflows / "outer-wf"
- outer_wf_dir.mkdir(parents=True)
- (outer_wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- _write_registry(outer_workflows, "outer-wf", enabled=False)
-
- # An unrelated nested project lives inside the outer workflow's own
- # directory tree, with its own separate installed workflow.
- inner_workflows = outer_wf_dir / "nested-proj" / ".specify" / "workflows"
- inner_wf_dir = inner_workflows / "inner-wf"
- inner_wf_dir.mkdir(parents=True)
- (inner_wf_dir / "workflow.yml").write_text(
- self.WORKFLOW_YAML.format(version="1.0.0"), encoding="utf-8"
- )
- _write_registry(inner_workflows, "inner-wf", enabled=True)
-
- unrelated_cwd = temp_dir / "unrelated-cwd"
- unrelated_cwd.mkdir()
- monkeypatch.chdir(unrelated_cwd)
-
- runner = CliRunner()
- target = inner_wf_dir / "workflow.yml"
- result = runner.invoke(app, ["workflow", "run", str(target)])
- # inner-wf (the actual nearest owner) is enabled -- must run, not
- # be blocked by the unrelated outer-wf's disabled state.
- assert result.exit_code == 0, result.output
-
- # The inverse proves this isn't just ignoring nesting: disabling
- # the true (nearest) owner must actually block this exact path.
- _write_registry(inner_workflows, "inner-wf", enabled=False)
- result = runner.invoke(app, ["workflow", "run", str(target)])
- assert result.exit_code != 0
- assert "disabled" in result.output
+ mode = stat.S_IMODE(registry.registry_path.stat().st_mode)
+ assert mode == 0o600, f"expected 0600, got {oct(mode)}"
@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_run_blocks_disabled_workflow_via_outward_alias_symlink(
- self, project_dir, monkeypatch
- ):
- """The inverse of the existing inward-symlink case: a path with no
- .specify/workflows segments at all (e.g. /tmp/alias.yml) that is
- itself a symlink resolving *into* installed storage must still
- receive the disabled check. Only checking the lexical path's own
- segments misses this alias entirely, since it has no such segments
- to begin with, and would let engine.load_workflow follow the
- symlink to the disabled workflow's real content unchecked."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0, result.output
-
- installed_yaml = (
- project_dir / ".specify" / "workflows" / "align-wf" / "workflow.yml"
- )
- external_dir = project_dir / "outside-alias"
- external_dir.mkdir()
- alias = external_dir / "alias.yml"
- alias.symlink_to(installed_yaml)
-
- result = runner.invoke(app, ["workflow", "run", str(alias)])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- result = runner.invoke(app, ["workflow", "enable", "align-wf"])
- assert result.exit_code == 0, result.output
- result = runner.invoke(app, ["workflow", "run", str(alias)])
- assert result.exit_code == 0, result.output
-
- _GATED_WORKFLOW_YAML = """
-schema_version: "1.0"
-workflow:
- id: "gated-wf"
- name: "Gated Workflow"
- version: "1.0.0"
-steps:
- - id: ask
- type: gate
- message: "Review"
- options: [approve, reject]
-"""
-
- def _install_and_run_gated(self, runner, app, project_dir):
- """Install a gate-step workflow and run it to a paused state.
-
- Returns the run_id. The gate step pauses without any interactive
- input, giving a resumable run tied to an installed workflow ID.
- """
- src = project_dir / "gated-src"
- src.mkdir(exist_ok=True)
- (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
- assert result.exit_code == 0, result.output
-
- result = runner.invoke(app, ["workflow", "run", "gated-wf", "--json"])
- assert result.exit_code == 0, result.output
- payload = json.loads(result.stdout)
- assert payload["status"] == "paused"
- return payload["run_id"]
-
- def test_unregistered_workflow_shaped_path_is_not_persisted_as_owner(
- self, project_dir, temp_dir, monkeypatch
- ):
- """A direct file is not installed merely because its path resembles
- installed storage; only registry membership establishes ownership."""
- import shutil
- from typer.testing import CliRunner
- from specify_cli import app
-
- standalone_root = temp_dir / "standalone-project"
- workflows_dir = standalone_root / ".specify" / "workflows"
- workflow_file = workflows_dir / "gated-wf" / "workflow.yml"
- workflow_file.parent.mkdir(parents=True)
- workflow_file.write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_ids = []
- for _ in range(2):
- result = runner.invoke(
- app, ["workflow", "run", str(workflow_file), "--json"]
- )
- assert result.exit_code == 0, result.output
- run_ids.append(json.loads(result.stdout)["run_id"])
-
- for run_id in run_ids:
- state_path = (
- project_dir
- / ".specify"
- / "workflows"
- / "runs"
- / run_id
- / "state.json"
- )
- state = json.loads(state_path.read_text(encoding="utf-8"))
- assert state["installed_workflow_id"] is None
- assert state["installed_registry_root"] is None
-
- shutil.rmtree(standalone_root)
- result = runner.invoke(
- app, ["workflow", "resume", run_ids[0], "--json"]
- )
- assert result.exit_code == 0, result.output
-
- workflows_dir.mkdir(parents=True)
- (workflows_dir / "workflow-registry.json").write_text(
- json.dumps(
- {
- "schema_version": "1.0",
- "workflows": {
- "gated-wf": {
- "name": "Unrelated workflow",
- "version": "9.9.9",
- "source": "dev",
- "enabled": False,
- }
- },
- }
- ),
- encoding="utf-8",
- )
- result = runner.invoke(
- app, ["workflow", "resume", run_ids[1], "--json"]
- )
- assert result.exit_code == 0, result.output
-
- def test_resume_blocks_when_installed_workflow_disabled(
- self, project_dir, monkeypatch
- ):
- """A run started from an installed workflow must not resume once
- that workflow is disabled. engine.resume() replays the persisted
- run directly from disk with no registry awareness at all, so the
- installed workflow's origin (id + owning registry root) is
- persisted at run start and re-checked against the registry's
- *current* state before resuming, mirroring `workflow run`'s
- disabled guard."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
- assert result.exit_code == 0, result.output
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- # Re-enabling must unblock the exact same run.
- result = runner.invoke(app, ["workflow", "enable", "gated-wf"])
- assert result.exit_code == 0, result.output
- result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert result.exit_code == 0, result.output
- resumed = json.loads(result.stdout)
- assert resumed["run_id"] == run_id
-
- def test_resume_rejects_corrupted_registry_entry(
+ def test_registry_save_rejects_swapped_temp_without_touching_target(
self, project_dir, monkeypatch
):
- from typer.testing import CliRunner
- from specify_cli import app
from specify_cli.workflows.catalog import WorkflowRegistry
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
+ import specify_cli.workflows.catalog as catalog_mod
registry = WorkflowRegistry(project_dir)
- registry.data["workflows"]["gated-wf"] = "corrupted"
- registry.save()
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert "corrupted" in result.output
-
- def test_resume_preload_io_error_is_reported_cleanly(
- self, project_dir, monkeypatch
- ):
- from unittest.mock import patch
- from typer.testing import CliRunner
- from specify_cli import app
- from specify_cli.workflows.engine import RunState
-
- monkeypatch.chdir(project_dir)
- with patch.object(
- RunState, "load", side_effect=OSError("permission [denied]")
- ):
- result = CliRunner().invoke(
- app, ["workflow", "resume", "unreadable-run"]
- )
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Resume failed" in result.output
- assert "permission [denied]" in result.output
-
- @pytest.mark.parametrize("malformation", ["non-object", "missing-run-id"])
- def test_resume_preload_rejects_malformed_state_cleanly(
- self, project_dir, monkeypatch, malformation
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
-
- if malformation == "non-object":
- state_path.write_text("[]", encoding="utf-8")
- else:
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data.pop("run_id")
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Invalid run state" in result.output
-
- def test_resume_rejects_out_of_range_current_step_index(
- self, project_dir, monkeypatch
- ):
- """An out-of-range positive index must fail cleanly, not silently
- complete the run with no steps executed.
-
- ``resume()`` slices ``definition.steps[state.current_step_index:]``;
- for any index >= len(steps) that slice is an empty list, so the run
- would otherwise finish with status "completed" having executed
- nothing.
- """
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data["current_step_index"] = 5
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
-
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Invalid run state" in result.output
- assert "out of range" in result.output
-
- reloaded = json.loads(state_path.read_text(encoding="utf-8"))
- assert reloaded["status"] == "paused"
-
- def test_resume_legacy_run_respects_current_disabled_state(
- self, project_dir, monkeypatch
- ):
- """Legacy runs infer same-project registry ownership before resume."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data.pop("installed_workflow_id", None)
- data.pop("installed_registry_root", None)
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
- assert result.exit_code == 0, result.output
-
- result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- def test_resume_migrates_legacy_installed_origin_metadata(
- self, project_dir, monkeypatch
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data.pop("installed_workflow_id", None)
- data.pop("installed_registry_root", None)
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert result.exit_code == 0, result.output
-
- migrated = json.loads(state_path.read_text(encoding="utf-8"))
- assert migrated["installed_workflow_id"] == "gated-wf"
- assert migrated["installed_registry_root"] is None
-
- def test_resume_blocks_after_project_moved_following_disable(
- self, temp_dir, monkeypatch
- ):
- """Renaming/moving the entire project after starting a run must not
- let a subsequent disable-then-resume bypass the guard. Persisting
- the run's *creation-time absolute* project path would make resume
- open a now-nonexistent old root (WorkflowRegistry falls back to an
- empty default there), missing the disabled entry that actually
- lives in the *current* (moved) project's registry. The common,
- same-project case must instead re-derive the owning root from the
- project's current location on every resume."""
- from typer.testing import CliRunner
- from specify_cli import app
- import shutil
-
- project_v1 = temp_dir / "project-v1"
- (project_v1 / ".specify" / "workflows").mkdir(parents=True)
- monkeypatch.chdir(project_v1)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_v1)
-
- project_v2 = temp_dir / "project-v2"
- monkeypatch.chdir(temp_dir)
- shutil.move(str(project_v1), str(project_v2))
- monkeypatch.chdir(project_v2)
-
- result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
- assert result.exit_code == 0, result.output
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- def test_resume_after_project_moved_still_works_when_enabled(
- self, temp_dir, monkeypatch
- ):
- """The inverse of the move regression: an enabled workflow's run
- must still resume normally after the project is moved -- the
- current-project fallback must not itself block legitimate
- resumes."""
- from typer.testing import CliRunner
- from specify_cli import app
- import shutil
-
- project_v1 = temp_dir / "project-v1-ok"
- (project_v1 / ".specify" / "workflows").mkdir(parents=True)
- monkeypatch.chdir(project_v1)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_v1)
-
- project_v2 = temp_dir / "project-v2-ok"
- monkeypatch.chdir(temp_dir)
- shutil.move(str(project_v1), str(project_v2))
- monkeypatch.chdir(project_v2)
-
- result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert result.exit_code == 0, result.output
-
- @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
- def test_resume_respects_cross_project_registry_root(
- self, temp_dir, monkeypatch
- ):
- """A run started via a direct workflow.yml path belonging to a
- different project than the cwd used for `workflow run`/`workflow
- resume` must still gate resuming on *that* owning project's
- registry, not the cwd project's (which has no entry for this ID
- at all). This is the genuine cross-project case that must remain
- unaffected by only special-casing the common same-project one."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- owner_project = temp_dir / "owner-project"
- (owner_project / ".specify" / "workflows").mkdir(parents=True)
- monkeypatch.chdir(owner_project)
- runner = CliRunner()
- src = owner_project / "gated-src"
- src.mkdir()
- (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
- assert result.exit_code == 0, result.output
-
- unrelated_cwd = temp_dir / "unrelated-cwd"
- unrelated_cwd.mkdir()
- monkeypatch.chdir(unrelated_cwd)
-
- owner_alias = temp_dir / "owner-project-alias"
- owner_alias.symlink_to(owner_project, target_is_directory=True)
- target = owner_alias / ".specify" / "workflows" / "gated-wf" / "workflow.yml"
- result = runner.invoke(app, ["workflow", "run", str(target), "--json"])
- assert result.exit_code == 0, result.output
- run_id = json.loads(result.stdout)["run_id"]
- state_path = (
- unrelated_cwd
- / ".specify"
- / "workflows"
- / "runs"
- / run_id
- / "state.json"
- )
- state = json.loads(state_path.read_text(encoding="utf-8"))
- assert state["installed_registry_root"] == str(owner_project.resolve())
-
- monkeypatch.chdir(owner_project)
- result = runner.invoke(app, ["workflow", "disable", "gated-wf"])
- assert result.exit_code == 0, result.output
-
- # Resume must run from unrelated_cwd (where this run's own
- # state.json actually lives) yet still be blocked by the owner
- # project's disabled entry.
- monkeypatch.chdir(unrelated_cwd)
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert "disabled" in result.output
-
- def test_resume_rejects_missing_cross_project_owner_root(
- self, temp_dir, monkeypatch
- ):
- """A vanished explicit cross-project owner cannot be safely
- rediscovered, so resume must fail closed instead of consulting the
- unrelated project that stores the run state."""
- from typer.testing import CliRunner
- from specify_cli import app
- import shutil
-
- owner_project = temp_dir / "owner-project-2"
- (owner_project / ".specify" / "workflows").mkdir(parents=True)
- monkeypatch.chdir(owner_project)
- runner = CliRunner()
- src = owner_project / "gated-src"
- src.mkdir()
- (src / "workflow.yml").write_text(self._GATED_WORKFLOW_YAML, encoding="utf-8")
- result = runner.invoke(app, ["workflow", "add", str(src), "--dev"])
- assert result.exit_code == 0, result.output
-
- unrelated_cwd = temp_dir / "unrelated-cwd-2"
- unrelated_cwd.mkdir()
- monkeypatch.chdir(unrelated_cwd)
-
- target = owner_project / ".specify" / "workflows" / "gated-wf" / "workflow.yml"
- result = runner.invoke(app, ["workflow", "run", str(target), "--json"])
- assert result.exit_code == 0, result.output
- run_id = json.loads(result.stdout)["run_id"]
-
- # owner_project vanishes entirely -- its persisted absolute root
- # is now dangling.
- shutil.rmtree(owner_project)
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert "owner" in result.output.lower()
- assert "unavailable" in result.output.lower()
-
- @pytest.mark.parametrize(
- "field, bad_value",
- [
- ("installed_workflow_id", 123),
- ("installed_workflow_id", ["gated-wf"]),
- ("installed_workflow_id", {"id": "gated-wf"}),
- ("installed_workflow_id", True),
- ("installed_workflow_id", ""),
- ("installed_workflow_id", "gated-wf\n"),
- ("installed_registry_root", 123),
- ("installed_registry_root", ["."]),
- ("installed_registry_root", {"root": "."}),
- ("installed_registry_root", False),
- ("installed_registry_root", ""),
- ("installed_registry_root", "relative-owner"),
- ],
- )
- def test_resume_rejects_malformed_run_state_origin_fields(
- self, project_dir, monkeypatch, field, bad_value
- ):
- """RunState.load() rejects malformed or unsafe origin metadata
- before registry/path lookups and reports a clean CLI error."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data[field] = bad_value
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "resume", run_id])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Error" in result.output
-
- @pytest.mark.parametrize("command", ["resume", "status"])
- def test_state_load_errors_escape_rich_markup(
- self, project_dir, monkeypatch, command
- ):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- malicious_status = "[bold red]forged[/bold red]"
- data["status"] = malicious_status
- state_path.write_text(json.dumps(data), encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", command, run_id])
-
- assert result.exit_code != 0
- assert malicious_status in result.output
-
- @pytest.mark.parametrize(
- "installed_workflow_id, installed_registry_root",
- [
- (None, None),
- ("gated-wf", None),
- ],
- )
- def test_resume_accepts_valid_run_state_origin_fields(
- self, project_dir, monkeypatch, installed_workflow_id, installed_registry_root
- ):
- """Valid installed-origin values continue to load and resume."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
+ registry.add("first-wf", {"name": "First"})
+ registry.registry_path.chmod(0o640)
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data["installed_workflow_id"] = installed_workflow_id
- data["installed_registry_root"] = installed_registry_root
- state_path.write_text(json.dumps(data), encoding="utf-8")
+ victim = project_dir / "victim.txt"
+ victim.write_text("untouched", encoding="utf-8")
+ victim.chmod(0o600)
- result = runner.invoke(app, ["workflow", "resume", run_id, "--json"])
- assert result.exit_code == 0, result.output
+ tmp_path = None
+ real_mkstemp = catalog_mod.tempfile.mkstemp
+ real_dump = catalog_mod.json.dump
- @pytest.mark.parametrize(
- "field, bad_value",
- [
- ("installed_workflow_id", 123),
- ("installed_workflow_id", ["gated-wf"]),
- ("installed_registry_root", 123),
- ("installed_registry_root", ["."]),
- ],
- )
- def test_status_rejects_malformed_run_state_origin_fields(
- self, project_dir, monkeypatch, field, bad_value
- ):
- """`workflow status <run_id>` calls RunState.load() same as resume,
- but only caught FileNotFoundError -- the new type validation there
- (int/list instead of str-or-null) raises ValueError, which leaked
- as a raw unhandled traceback instead of `workflow resume`'s clean
- `[red]Error:[/red] {exc}` + exit 1. Must get the identical clean
- boundary, leaving the no-run-id list path (and FileNotFoundError
- behavior) unchanged."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- run_id = self._install_and_run_gated(runner, app, project_dir)
-
- state_path = (
- project_dir / ".specify" / "workflows" / "runs" / run_id / "state.json"
- )
- data = json.loads(state_path.read_text(encoding="utf-8"))
- data[field] = bad_value
- state_path.write_text(json.dumps(data), encoding="utf-8")
+ def tracking_mkstemp(*args, **kwargs):
+ nonlocal tmp_path
+ fd, name = real_mkstemp(*args, **kwargs)
+ tmp_path = Path(name)
+ return fd, name
- result = runner.invoke(app, ["workflow", "status", run_id])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Error" in result.output
-
- def test_status_run_not_found_unchanged(self, project_dir, monkeypatch):
- """FileNotFoundError behavior for a nonexistent run_id must remain
- exactly as before this fix."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "status", "nonexistent-run"])
- assert result.exit_code != 0
- assert "Run not found: nonexistent-run" in result.output
-
- def test_status_json_not_found_error_goes_to_stderr(
- self, project_dir, monkeypatch, capsys
- ):
- """Under --json, the not-found/invalid-run error must go to stderr so the
- stdout JSON stream stays parseable (empty on the error path) — mirroring
- `workflow run`/`workflow resume`. Before this fix both handlers used the
- stdout console, corrupting a consumer's json.loads(stdout)."""
- import typer
- from specify_cli.workflows import _commands
-
- (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
- monkeypatch.setattr(
- _commands, "_require_specify_project", lambda: project_dir
- )
- with pytest.raises(typer.Exit) as exc:
- _commands.workflow_status("does-not-exist", json_output=True)
- assert exc.value.exit_code == 1
- captured = capsys.readouterr()
- assert "Run not found" in captured.err
- assert "Run not found" not in captured.out
- # stdout carries no partial/corrupt JSON on the error path.
- assert captured.out.strip() == ""
-
- def test_status_json_invalid_run_error_goes_to_stderr(
- self, project_dir, monkeypatch, capsys
- ):
- """The ValueError handler (a malformed/invalid run state) must ALSO route
- to stderr under --json, not just the FileNotFoundError one — otherwise a
- regression there would silently corrupt the JSON stream and this suite
- wouldn't catch it."""
- import typer
- from specify_cli.workflows import _commands
- from specify_cli.workflows.engine import RunState
+ def swap_after_dump(*args, **kwargs):
+ result = real_dump(*args, **kwargs)
+ assert tmp_path is not None
+ tmp_path.unlink()
+ tmp_path.symlink_to(victim)
+ return result
- (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
- monkeypatch.setattr(
- _commands, "_require_specify_project", lambda: project_dir
- )
+ monkeypatch.setattr(catalog_mod.tempfile, "mkstemp", tracking_mkstemp)
+ monkeypatch.setattr(catalog_mod.json, "dump", swap_after_dump)
- def _raise_value_error(*args, **kwargs):
- raise ValueError("corrupt run state: bad status")
+ with pytest.raises(OSError):
+ registry.add("second-wf", {"name": "Second"})
- monkeypatch.setattr(RunState, "load", _raise_value_error)
+ assert victim.read_text(encoding="utf-8") == "untouched"
+ if sys.platform != "win32":
+ assert stat.S_IMODE(victim.stat().st_mode) == 0o600
+ assert not registry.registry_path.is_symlink()
+ assert WorkflowRegistry(project_dir).is_installed("first-wf")
- with pytest.raises(typer.Exit) as exc:
- _commands.workflow_status("some-run", json_output=True)
- assert exc.value.exit_code == 1
- captured = capsys.readouterr()
- assert "corrupt run state" in captured.err
- assert "corrupt run state" not in captured.out
- assert captured.out.strip() == ""
+ @pytest.mark.skipif(sys.platform == "win32", reason="chmod mode bits not reliable on Windows")
+ def test_registry_save_failure_preserves_file_on_disk(self, project_dir, monkeypatch):
+ """A failed dump must not truncate the persisted registry, and must
+ not alter its on-disk mode either -- the chmod-to-match-existing-mode
+ step operates on the temp file, never the target, so a failed save
+ (which never reaches os.replace) cannot touch the original's mode."""
+ from specify_cli.workflows.catalog import WorkflowRegistry
- def test_status_unreadable_run_state_exits_cleanly(
- self, project_dir, monkeypatch
- ):
- """`workflow status <run_id>` gained a ValueError boundary to match
- `workflow resume`, but not resume's OSError one -- so an unreadable
- state.json (bad permissions, a directory in its place, an I/O error)
- still leaked a raw traceback. exists() is True for a directory, so
- the guard passes and open() raises OSError."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runs_dir = project_dir / ".specify" / "workflows" / "runs" / "abc123"
- runs_dir.mkdir(parents=True, exist_ok=True)
- # A directory where state.json should be: exists() passes, open() fails.
- (runs_dir / "state.json").mkdir(exist_ok=True)
+ registry = WorkflowRegistry(project_dir)
+ registry.add("align-wf", {"version": "1.0.0", "source": "catalog"})
+ registry.registry_path.chmod(0o644)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "status", "abc123"])
- assert result.exit_code != 0
- assert result.exception is None or isinstance(result.exception, SystemExit)
- assert "Error" in result.output
+ import specify_cli.workflows.catalog as catalog_mod
- def test_status_json_unreadable_run_state_error_goes_to_stderr(
- self, project_dir, monkeypatch, capsys
- ):
- """The OSError handler must route to stderr under --json too, so the
- stdout JSON stream stays parseable -- mirroring the sibling
- FileNotFoundError/ValueError handlers."""
- import typer
- from specify_cli.workflows import _commands
- from specify_cli.workflows.engine import RunState
+ def boom(*args, **kwargs):
+ raise OSError("disk full")
- (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
- monkeypatch.setattr(
- _commands, "_require_specify_project", lambda: project_dir
- )
+ monkeypatch.setattr(catalog_mod.json, "dump", boom)
+ with pytest.raises(OSError):
+ registry.add("align-wf", {"version": "2.0.0", "source": "catalog"})
+ monkeypatch.undo()
- def _raise_os_error(*args, **kwargs):
- raise PermissionError(13, "Permission denied")
-
- monkeypatch.setattr(RunState, "load", _raise_os_error)
-
- with pytest.raises(typer.Exit) as exc:
- _commands.workflow_status("some-run", json_output=True)
- assert exc.value.exit_code == 1
- captured = capsys.readouterr()
- assert "Permission denied" in captured.err
- assert "Permission denied" not in captured.out
- assert captured.out.strip() == ""
-
- def test_status_no_run_id_list_path_unaffected(self, project_dir, monkeypatch):
- """The no-run-id list-all-runs path must remain unaffected by the
- new single-run ValueError boundary."""
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- (project_dir / ".specify" / "workflows").mkdir(parents=True, exist_ok=True)
- runner = CliRunner()
- result = runner.invoke(app, ["workflow", "status"])
- assert result.exit_code == 0, result.output
-
- def test_disable_shows_marker_in_list(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
- runner.invoke(app, ["workflow", "disable", "align-wf"])
- result = runner.invoke(app, ["workflow", "list"])
- assert result.exit_code == 0, result.output
- assert "[disabled]" in result.output
-
- def test_enable_disable_not_installed_errors(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- for cmd in ("enable", "disable"):
- result = runner.invoke(app, ["workflow", cmd, "ghost"])
- assert result.exit_code != 0
- assert "not installed" in result.output
-
- def test_enable_disable_idempotent_warnings(self, project_dir, monkeypatch):
- from typer.testing import CliRunner
- from specify_cli import app
-
- monkeypatch.chdir(project_dir)
- runner = CliRunner()
- self._install_dev(runner, app, project_dir)
-
- result = runner.invoke(app, ["workflow", "enable", "align-wf"])
- assert result.exit_code == 0
- assert "already enabled" in result.output
-
- runner.invoke(app, ["workflow", "disable", "align-wf"])
- result = runner.invoke(app, ["workflow", "disable", "align-wf"])
- assert result.exit_code == 0
- assert "already disabled" in result.output
+ fresh = WorkflowRegistry(project_dir)
+ assert fresh.get("align-wf")["version"] == "1.0.0"
+ assert stat.S_IMODE(registry.registry_path.stat().st_mode) == 0o644
+ assert not list(registry.workflows_dir.glob("*.tmp"))
diff --git a/tests/unit/test_condition_expression_block.py b/tests/unit/test_condition_expression_block.py
index 7a30a2f42..528798d5e 100644
--- a/tests/unit/test_condition_expression_block.py
+++ b/tests/unit/test_condition_expression_block.py
@@ -26,9 +26,9 @@ from specify_cli.workflows.expressions import (
_WORD_OPERATORS,
format_condition_remediation,
)
-from specify_cli.workflows.steps.do_while import DoWhileStep
-from specify_cli.workflows.steps.if_then import IfThenStep
-from specify_cli.workflows.steps.while_loop import WhileStep
+from specify_cli.workflows.step.do_while import DoWhileStep
+from specify_cli.workflows.step.if_then import IfThenStep
+from specify_cli.workflows.step.while_loop import WhileStep
STEP_CLASSES = [IfThenStep, WhileStep, DoWhileStep]
diff --git a/tests/workflows/test_overlay_commands.py b/tests/workflows/test_overlay_commands.py
deleted file mode 100644
index 8ac8d0663..000000000
--- a/tests/workflows/test_overlay_commands.py
+++ /dev/null
@@ -1,1172 +0,0 @@
-"""Tests for workflow overlay CLI commands."""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-import pytest
-import typer
-import yaml
-from typer.testing import CliRunner
-
-from specify_cli import app
-
-
-runner = CliRunner()
-
-
-def project_dir(tmp_path):
- """Create a mock spec-kit project with ``.specify/workflows/`` directory."""
- workflows_dir = tmp_path / ".specify" / "workflows"
- workflows_dir.mkdir(parents=True, exist_ok=True)
- return tmp_path
-
-
-def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:
- wf_dir = project_root / ".specify" / "workflows" / workflow_id
- wf_dir.mkdir(parents=True, exist_ok=True)
- wf_path = wf_dir / "workflow.yml"
- wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")
- return wf_path
-
-
-def _write_overlay(project_root: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:
- ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
- ov_dir.mkdir(parents=True, exist_ok=True)
- ov_path = ov_dir / f"{overlay_id}.yml"
- ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
- return ov_path
-
-
-class TestOverlayCli:
- """CLI-level tests for ``specify workflow overlay *``."""
-
- def test_overlay_add(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
- )
- assert result.exit_code == 0, result.output
- assert "Overlay 'ov1' added" in result.output
-
- installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- assert installed.is_file()
- data = yaml.safe_load(installed.read_text(encoding="utf-8"))
- assert data["priority"] == 5
-
- def test_overlay_add_reuses_yaml_extension(self, project_dir, monkeypatch):
- """If <id>.yaml already exists, overlay add must write to it instead of creating <id>.yml."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # Pre-create the overlay using the .yaml extension.
- existing_yaml = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yaml"
- existing_yaml.parent.mkdir(parents=True, exist_ok=True)
- existing_yaml.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 1,
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
-
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 20,
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
- assert result.exit_code == 0, result.output
-
- # Should have written to the pre-existing .yaml file.
- assert existing_yaml.is_file()
- data = yaml.safe_load(existing_yaml.read_text(encoding="utf-8"))
- assert data["priority"] == 10
-
- # Must NOT have created a duplicate .yml alongside the .yaml.
- duplicate_yml = existing_yaml.with_suffix(".yml")
- assert not duplicate_yml.exists(), "duplicate .yml was created alongside existing .yaml"
- assert list(existing_yaml.parent.glob(f".{existing_yaml.name}.*.bak")) == []
-
- def test_overlay_add_with_priority_override_missing_in_file(self, project_dir, monkeypatch):
- """--priority must fix a missing priority in the overlay file."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # Overlay file has NO priority field
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
- )
- assert result.exit_code == 0, result.output
- assert "Overlay 'ov1' added" in result.output
-
- installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- assert installed.is_file()
- data = yaml.safe_load(installed.read_text(encoding="utf-8"))
- assert data["priority"] == 5
-
- def test_overlay_add_defaults_priority_to_ten(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
-
- assert result.exit_code == 0, result.output
- installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- assert yaml.safe_load(installed.read_text(encoding="utf-8"))["priority"] == 10
-
- def test_overlay_add_rejects_non_positive_priority(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(
- app,
- ["workflow", "overlay", "add", str(overlay_file), "--priority", "0"],
- )
-
- assert result.exit_code == 1
- assert "must be >= 1" in result.output
-
- def test_overlay_add_keeps_non_ascii_text_readable(
- self, project_dir, monkeypatch
- ):
- """``overlay add`` must not escape non-ASCII text in the written file.
-
- Overlay files are documented as hand-authored, so writing them back
- with ``\\uXXXX`` escapes makes the user's own file unreadable.
- """
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- message = "Revisar el plan — ¿aprobar? 日本語"
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "replace",
- "anchor": "a",
- "step": {
- "id": "a",
- "type": "gate",
- "message": message,
- "options": ["approve"],
- },
- }
- ],
- },
- allow_unicode=True,
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
- assert result.exit_code == 0, result.output
-
- installed = (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- )
- text = installed.read_text(encoding="utf-8")
- assert message in text, text
- assert "\\u" not in text and "\\x" not in text, text
- # The value must still round-trip identically.
- data = yaml.safe_load(text)
- assert data["edits"][0]["step"]["message"] == message
-
- def test_overlay_set_priority_keeps_non_ascii_text_readable(
- self, project_dir, monkeypatch
- ):
- """Toggling an overlay must not mangle non-ASCII text already in it."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- message = "Revisar el plan — ¿aprobar? 日本語"
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "replace",
- "anchor": "a",
- "step": {
- "id": "a",
- "type": "gate",
- "message": message,
- "options": ["approve"],
- },
- }
- ],
- },
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf", "ov1", "20"]
- )
- assert result.exit_code == 0, result.output
-
- text = (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- ).read_text(encoding="utf-8")
- assert message in text, text
- assert "\\u" not in text and "\\x" not in text, text
- data = yaml.safe_load(text)
- assert data["priority"] == 20
- assert data["edits"][0]["step"]["message"] == message
-
- def test_overlay_set_priority(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf", "ov1", "20"]
- )
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- ).read_text(encoding="utf-8")
- )
- assert data["priority"] == 20
- assert list(
- (project_dir / ".specify" / "workflows" / "overlays" / "wf").glob(
- ".ov1.yml.*.bak"
- )
- ) == []
-
- def test_overlay_set_priority_rejects_zero(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
-
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf", "ov1", "0"]
- )
-
- assert result.exit_code == 1
- assert "must be >= 1" in result.output
-
- def test_overlay_set_priority_rejects_ids_with_trailing_newline(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf", "ov1\n", "20"]
- )
- assert result.exit_code == 1
- assert "Invalid overlay ID" in result.output
-
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf\n", "ov1", "20"]
- )
- assert result.exit_code == 1
- assert "Invalid workflow ID" in result.output
-
- def test_overlay_disable_and_enable(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "ov1"])
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- ).read_text(encoding="utf-8")
- )
- assert data["enabled"] is False
-
- result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "ov1"])
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- ).read_text(encoding="utf-8")
- )
- assert data["enabled"] is True
-
- def test_overlay_remove(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "ov1"])
- assert result.exit_code == 0, result.output
- assert not (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"
- ).exists()
-
- def test_overlay_list(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
- assert result.exit_code == 0, result.output
- assert "ov1" in result.output
-
- def test_overlay_list_shows_disabled_overlay(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "enabled": False,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
- assert result.exit_code == 0, result.output
- assert "ov1" in result.output
- assert "disabled" in result.output
-
- def test_workflow_resolve(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "resolve", "wf"])
- assert result.exit_code == 0, result.output
- assert "base" in result.output
- assert "project:ov1" in result.output
- assert "new" in result.output
- assert "priority=n/a" in result.output
-
- from specify_cli.workflows.overlays._commands import workflow_resolve
-
- payload = workflow_resolve(project_dir, "wf")
- assert payload is not None
- assert payload["layers"][-1]["tier"] == "base"
- assert payload["layers"][-1]["priority"] is None
-
- def test_workflow_resolve_prints_tier_labels(self, project_dir, monkeypatch):
- """Layer tiers render literally; an unescaped ``[base]`` is eaten as markup."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "resolve", "wf"])
- assert result.exit_code == 0, result.output
- assert "[base]" in result.output
- assert "[project-overlay]" in result.output
-
- @pytest.mark.parametrize(
- "step_id",
- [
- # Balanced tag: silently swallowed, so the step vanishes from output.
- "new[stuff]",
- # Unbalanced closer: raises MarkupError -> traceback and exit 1.
- "new[/red]",
- ],
- )
- def test_workflow_resolve_escapes_rich_markup_in_step_id(
- self, project_dir, monkeypatch, step_id
- ):
- """Step IDs are unvalidated for brackets, so they must be escaped."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": step_id, "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "resolve", "wf"])
- assert result.exit_code == 0, result.output
- assert step_id in result.output
-
- def test_workflow_resolve_equal_priority_layers_sort_by_source(self, project_dir, monkeypatch):
- """Equal-priority overlays are listed alphabetically by source."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # "zzz" sorts last alphabetically, so the composer applies it last and wins.
- # Resolver layer output follows the common priority/source sort order.
- _write_overlay(
- project_dir,
- "wf",
- "aaa",
- {
- "id": "aaa",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "aaa-step", "type": "command", "command": "echo"},
- }
- ],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "zzz",
- {
- "id": "zzz",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "zzz-step", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- result = runner.invoke(app, ["workflow", "resolve", "wf"])
- assert result.exit_code == 0, result.output
- zzz_pos = result.output.index("project:zzz")
- aaa_pos = result.output.index("project:aaa")
- assert aaa_pos < zzz_pos
-
- def test_workflow_add_does_not_copy_overlays(self, project_dir, monkeypatch, tmp_path):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- source_dir = tmp_path / "source-wf"
- source_dir.mkdir()
- (source_dir / "workflow.yml").write_text(
- yaml.safe_dump(
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- }
- ),
- encoding="utf-8",
- )
- overlays_dir = source_dir / "overlays"
- overlays_dir.mkdir()
- (overlays_dir / "ov1.yml").write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(app, ["workflow", "add", str(source_dir)])
- assert result.exit_code == 0, result.output
- # Overlays in the source directory should NOT be copied — workflow add
- # only installs the workflow.yml, not sibling overlays.
- installed_overlay = (
- project_dir / ".specify" / "workflows" / "wf" / "overlays" / "ov1.yml"
- )
- assert not installed_overlay.exists()
-
-
-class TestOverlayFilenameVsManifestId:
- """Overlay identity must come from the manifest ``id`` field, not the filename.
-
- This matches the project-wide convention: presets use ``preset.id``,
- extensions use ``extension.id``, workflows use ``workflow.id``, and
- workflow steps use ``step.type_key``. Overlays must follow the same pattern.
- """
-
- def _write_mismatched_overlay(
- self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict
- ) -> Path:
- """Write an overlay file where filename != manifest id."""
- ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
- ov_dir.mkdir(parents=True, exist_ok=True)
- ov_path = ov_dir / filename
- ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
- return ov_path
-
- def test_find_overlay_by_manifest_id_not_filename(self, project_dir, monkeypatch):
- """_find_overlay_file must locate overlays by manifest id, not filename."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # File is named "custom.yml" but manifest declares id: "lint"
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "custom.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- },
- )
-
- from specify_cli.workflows.overlays._commands import _find_overlay_file
-
- # Must find by manifest id "lint", not by filename "custom"
- found = _find_overlay_file(project_dir, "wf", "lint")
- assert found is not None
- assert found.name == "custom.yml"
-
- # Must NOT find by filename stem "custom"
- not_found = _find_overlay_file(project_dir, "wf", "custom")
- assert not_found is None
-
- def test_enable_disable_with_mismatched_filename(self, project_dir, monkeypatch):
- """enable/disable must work when filename != manifest id."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "custom.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "lint"])
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
- encoding="utf-8"
- )
- )
- assert data["enabled"] is False
-
- result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "lint"])
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
- encoding="utf-8"
- )
- )
- assert data["enabled"] is True
-
- def test_set_priority_with_mismatched_filename(self, project_dir, monkeypatch):
- """set-priority must work when filename != manifest id."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "custom.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "set-priority", "wf", "lint", "25"])
- assert result.exit_code == 0, result.output
- data = yaml.safe_load(
- (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(
- encoding="utf-8"
- )
- )
- assert data["priority"] == 25
-
- def test_remove_with_mismatched_filename(self, project_dir, monkeypatch):
- """remove must work when filename != manifest id."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "custom.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- },
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "lint"])
- assert result.exit_code == 0, result.output
- assert not (
- project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml"
- ).exists()
-
- def test_duplicate_manifest_id_is_rejected(self, project_dir, monkeypatch):
- """Two files with the same manifest ID are ambiguous."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # Two files, both declare id: "lint"
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "aaa.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- },
- )
- self._write_mismatched_overlay(
- project_dir,
- "wf",
- "zzz.yml",
- "lint",
- {
- "id": "lint",
- "extends": "wf",
- "priority": 20,
- "edits": [{"remove": "a"}],
- },
- )
-
- from specify_cli.workflows.overlays._commands import _find_overlay_file
-
- with pytest.raises(typer.Exit):
- _find_overlay_file(project_dir, "wf", "lint")
-
-
-class TestOverlayAddDoesNotClobber:
- """`overlay add` must not destroy a different overlay sitting at <id>.yml.
-
- Overlay identity is the manifest `id`, not the filename (see
- `_find_overlay_file`), so `lint.yml` can legitimately contain
- `id: format`. When `_find_overlay_file` found no file carrying the new
- overlay's id, the fallback target was derived purely from the filename and
- committed onto unconditionally — permanently destroying the occupant, since
- the commit renames it to a `.bak` and the success path then discards that
- backup. Exit code 0, no warning.
- """
-
- def _setup(self, project_dir: Path, occupant_id: str | None) -> tuple[Path, Path]:
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- ov_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
- ov_dir.mkdir(parents=True, exist_ok=True)
- if occupant_id is not None:
- (ov_dir / "lint.yml").write_text(
- yaml.safe_dump(
- {
- "id": occupant_id,
- "extends": "wf",
- "priority": 3,
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
- incoming = project_dir / "incoming.yml"
- incoming.write_text(
- yaml.safe_dump(
- {
- "id": "lint",
- "extends": "wf",
- "priority": 10,
- "edits": [{"remove": "a"}],
- }
- ),
- encoding="utf-8",
- )
- return ov_dir, incoming
-
- def test_add_does_not_clobber_a_different_overlay(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id="format")
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 1, result.output
- # The victim must be untouched, and no backup left lying around.
- survivor = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
- assert survivor["id"] == "format", survivor
- assert survivor["priority"] == 3, survivor
- assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
-
- def test_add_still_updates_the_same_overlay_in_place(
- self, project_dir, monkeypatch
- ):
- """The guard must only fire for a *different* overlay id."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id="lint")
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 0, result.output
- updated = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
- assert updated["id"] == "lint"
- assert updated["priority"] == 10
-
- def test_add_refuses_a_directory_occupant(self, project_dir, monkeypatch):
- """A non-regular occupant must be refused, not renamed aside.
-
- The guard used `Path.is_file()`, which is False for a directory (and on
- POSIX for a FIFO or socket), so such a destination bypassed it entirely
- and reached `_commit_workflow_file` -- which renames whatever is there
- to a `.bak` sibling and discards it on the success path. The command
- reported success while moving the user's directory away; it survived
- only because unlinking a directory happens to fail.
- """
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id=None)
- occupant = ov_dir / "lint.yml"
- occupant.mkdir()
- (occupant / "precious.txt").write_text("user data", encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 1, result.output
- # Rich wraps console output, so normalise whitespace before matching.
- assert "not a regular file" in " ".join(result.output.split())
- # Untouched, still a directory, contents intact, nothing renamed aside.
- assert occupant.is_dir()
- assert (occupant / "precious.txt").read_text(encoding="utf-8") == "user data"
- assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
-
- @pytest.mark.skipif(
- not hasattr(os, "mkfifo"), reason="FIFOs are POSIX-only"
- )
- def test_add_refuses_a_fifo_occupant(self, project_dir, monkeypatch):
- """A FIFO has no accidental protection: it is renamed aside and deleted."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id=None)
- occupant = ov_dir / "lint.yml"
- os.mkfifo(occupant)
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 1, result.output
- assert "not a regular file" in " ".join(result.output.split())
- assert occupant.is_fifo()
- assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
-
- @pytest.mark.parametrize(
- "raw",
- [
- "id: [1, 2\n bad: yaml:\n",
- "- just\n- a\n- sequence\n",
- "just a scalar\n",
- "extends: wf\npriority: 3\n",
- "id: 5\nextends: wf\npriority: 3\n",
- ],
- ids=["malformed", "sequence", "scalar", "missing_id", "non_string_id"],
- )
- def test_add_fails_closed_when_the_occupant_cannot_be_identified(
- self, project_dir, monkeypatch, raw
- ):
- """An unidentifiable occupant must be refused, not silently destroyed.
-
- `_find_overlay_file` matches on the manifest `id` and skips exactly the
- files whose identity cannot be established — unreadable, malformed,
- non-mapping, or missing a usable `id`. Those therefore fall through to
- the filename-derived target, so a guard that only refuses a *different
- valid* id would still let `_commit_workflow_file` discard the user's
- file. It is destroyed just as permanently as a valid overlay, only
- without even being able to name what was lost.
- """
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id=None)
- occupant = ov_dir / "lint.yml"
- occupant.write_text(raw, encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 1, result.output
- # Byte-for-byte survival, and no backup left behind.
- assert occupant.read_text(encoding="utf-8") == raw
- assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
-
- def test_add_creates_the_file_when_absent(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- ov_dir, incoming = self._setup(project_dir, occupant_id=None)
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
-
- assert result.exit_code == 0, result.output
- created = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
- assert created["id"] == "lint"
diff --git a/tests/workflows/test_overlay_composer.py b/tests/workflows/test_overlay_composer.py
index 1092be921..284033007 100644
--- a/tests/workflows/test_overlay_composer.py
+++ b/tests/workflows/test_overlay_composer.py
@@ -7,10 +7,10 @@ from pathlib import Path
import pytest
import yaml
-from specify_cli.workflows.overlays import WorkflowResolver
-from specify_cli.workflows.overlays.composer import StepListComposer
-from specify_cli.workflows.overlays.layer_sources import BaseWorkflowSource, Layer
-from specify_cli.workflows.overlays.schema import Overlay, OverlayEdit
+from specify_cli.workflows.overlay import WorkflowResolver
+from specify_cli.workflows.overlay.composer import StepListComposer
+from specify_cli.workflows.overlay.layer_sources import BaseWorkflowSource, Layer
+from specify_cli.workflows.overlay.schema import Overlay, OverlayEdit
def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:
diff --git a/tests/workflows/test_overlay_layer_sources.py b/tests/workflows/test_overlay_layer_sources.py
index d852cb762..172115df0 100644
--- a/tests/workflows/test_overlay_layer_sources.py
+++ b/tests/workflows/test_overlay_layer_sources.py
@@ -8,7 +8,7 @@ from unittest.mock import patch
import pytest
import yaml
-from specify_cli.workflows.overlays.layer_sources import (
+from specify_cli.workflows.overlay.layer_sources import (
BaseWorkflowSource,
OverlayLoadError,
ProjectOverlaySource,
diff --git a/tests/workflows/test_overlay_merge.py b/tests/workflows/test_overlay_merge.py
index 3865e47a8..20c7571f3 100644
--- a/tests/workflows/test_overlay_merge.py
+++ b/tests/workflows/test_overlay_merge.py
@@ -7,14 +7,14 @@ from typing import Any
import pytest
-from specify_cli.workflows.overlays.merge import (
+from specify_cli.workflows.overlay.merge import (
ComposedStep,
OverlayLayer,
find_step,
merge_steps,
validate_edits,
)
-from specify_cli.workflows.overlays.schema import Overlay, OverlayEdit
+from specify_cli.workflows.overlay.schema import Overlay, OverlayEdit
def _step(id: str, **kwargs: Any) -> dict[str, Any]: # noqa: A002
diff --git a/tests/workflows/test_overlay_schema.py b/tests/workflows/test_overlay_schema.py
index a91efb0a3..ed5f527a6 100644
--- a/tests/workflows/test_overlay_schema.py
+++ b/tests/workflows/test_overlay_schema.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import pytest
-from specify_cli.workflows.overlays.schema import (
+from specify_cli.workflows.overlay.schema import (
OverlayEdit,
validate_overlay_yaml,
)
diff --git a/tests/workflows/test_overlay_security.py b/tests/workflows/test_overlay_security.py
deleted file mode 100644
index a1249ad84..000000000
--- a/tests/workflows/test_overlay_security.py
+++ /dev/null
@@ -1,321 +0,0 @@
-"""Security tests for workflow overlay path handling."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-import yaml
-from typer.testing import CliRunner
-
-from specify_cli import app
-
-
-runner = CliRunner()
-
-
-def project_dir(tmp_path):
- """Create a mock spec-kit project with ``.specify/workflows/`` directory."""
- workflows_dir = tmp_path / ".specify" / "workflows"
- workflows_dir.mkdir(parents=True, exist_ok=True)
- return tmp_path
-
-
-def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:
- wf_dir = project_root / ".specify" / "workflows" / workflow_id
- wf_dir.mkdir(parents=True, exist_ok=True)
- wf_path = wf_dir / "workflow.yml"
- wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")
- return wf_path
-
-
-def _write_overlay(project_root: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:
- ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id
- ov_dir.mkdir(parents=True, exist_ok=True)
- ov_path = ov_dir / f"{overlay_id}.yml"
- ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")
- return ov_path
-
-
-class TestOverlayPathTraversal:
- """Overlay CLI must stay inside the overlay directory."""
-
- def test_overlay_add_rejects_traversal_in_workflow_id(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "../wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
- )
- assert result.exit_code != 0, result.output
- assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
-
- def test_overlay_add_rejects_traversal_in_overlay_id(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "../../ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(
- app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]
- )
- assert result.exit_code != 0, result.output
- assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
-
- def test_overlay_remove_cannot_escape_overlays_dir(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- # Create a base workflow file that would be the traversal target.
- target = project_dir / ".specify" / "workflows" / "wf" / "workflow.yml"
- assert target.is_file()
-
- result = runner.invoke(
- app, ["workflow", "overlay", "remove", "wf", "../wf/workflow"]
- )
- assert result.exit_code != 0, result.output
- assert target.is_file()
- assert "Invalid" in result.output or "traversal" in result.output.lower()
-
- def test_overlay_remove_rejects_symlink(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- _write_overlay(
- project_dir,
- "wf",
- "ov1",
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- },
- )
-
- overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
- real_file = overlay_dir / "ov1.yml"
- symlink_file = overlay_dir / "symlink.yml"
- symlink_file.symlink_to(real_file)
-
- result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "symlink"])
- assert result.exit_code != 0, result.output
- assert real_file.is_file()
- assert "symlink" in result.output.lower() or "Invalid" in result.output
-
- def test_overlay_add_rejects_symlinked_target_file(self, project_dir, monkeypatch):
- """overlay add must not overwrite through a symlinked overlay file target."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
-
- overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
- overlay_dir.mkdir(parents=True, exist_ok=True)
- real_file = overlay_dir / "other.yml"
- real_file.write_text("sentinel\n", encoding="utf-8")
- (overlay_dir / "ov1.yml").symlink_to(real_file)
-
- overlay_file = project_dir / "overlay.yml"
- overlay_file.write_text(
- yaml.safe_dump(
- {
- "id": "ov1",
- "extends": "wf",
- "priority": 10,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "new", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])
-
- assert result.exit_code != 0, result.output
- assert "symlinked path" in result.output.lower()
- assert real_file.read_text(encoding="utf-8") == "sentinel\n"
-
- @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])
- def test_overlay_operations_reject_reserved_workflow_id(
- self, project_dir, monkeypatch, workflow_id
- ):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- result = runner.invoke(app, ["workflow", "overlay", "list", workflow_id])
- assert result.exit_code != 0, result.output
- assert "Invalid" in result.output or "reserved" in result.output.lower()
-
- def test_overlay_set_priority_rejects_traversal(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- result = runner.invoke(
- app, ["workflow", "overlay", "set-priority", "wf", "../other", "10"]
- )
- assert result.exit_code != 0, result.output
- assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
-
- def test_overlay_enable_rejects_traversal(self, project_dir, monkeypatch):
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "../other"])
- assert result.exit_code != 0, result.output
- assert "invalid" in result.output.lower() or "traversal" in result.output.lower()
-
- def test_overlay_rejects_symlinked_overlays_dir(self, project_dir, monkeypatch, tmp_path):
- """Overlay commands must reject a symlinked .specify/workflows/overlays directory."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
-
- # Create a symlinked overlays directory pointing outside the project
- outside_dir = tmp_path / "outside"
- outside_dir.mkdir()
- overlays_dir = project_dir / ".specify" / "workflows" / "overlays"
- overlays_dir.symlink_to(outside_dir)
-
- result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
- assert result.exit_code != 0, result.output
- assert "symlink" in result.output.lower()
-
- def test_overlay_list_rejects_symlinked_per_workflow_dir(self, project_dir, monkeypatch, tmp_path):
- """Overlay list must reject a symlinked per-workflow overlay directory."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
-
- # Create a real overlay directory outside the project.
- outside_dir = tmp_path / "outside_wf"
- outside_dir.mkdir()
- outside_dir.joinpath("evil.yml").write_text(
- yaml.safe_dump(
- {
- "id": "evil",
- "extends": "wf",
- "priority": 100,
- "edits": [
- {
- "operation": "insert_after",
- "anchor": "a",
- "step": {"id": "evil-step", "type": "command", "command": "echo"},
- }
- ],
- }
- ),
- encoding="utf-8",
- )
-
- # Symlink the per-workflow overlay directory to the outside location.
- overlays_root = project_dir / ".specify" / "workflows" / "overlays"
- overlays_root.mkdir(parents=True, exist_ok=True)
- symlink_dir = overlays_root / "wf"
- symlink_dir.symlink_to(outside_dir)
-
- result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
- assert result.exit_code != 0, result.output
- assert "symlink" in result.output.lower()
-
- def test_overlay_list_reports_invalid_yaml_cleanly(self, project_dir, monkeypatch):
- """Overlay list should surface malformed overlay YAML as a clean user error."""
- monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
- _write_workflow(
- project_dir,
- "wf",
- {
- "schema_version": "1.0",
- "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
- "steps": [{"id": "a", "type": "command", "command": "echo"}],
- },
- )
- overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
- overlay_dir.mkdir(parents=True, exist_ok=True)
- (overlay_dir / "broken.yml").write_text("id: broken\nextends: wf\npriority: [\n", encoding="utf-8")
-
- result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])
-
- assert result.exit_code != 0, result.output
- assert "Invalid YAML" in result.output
diff --git a/tests/workflows/test_resolver_integration.py b/tests/workflows/test_resolver_integration.py
index 6f6ab9d65..2c5871b5c 100644
--- a/tests/workflows/test_resolver_integration.py
+++ b/tests/workflows/test_resolver_integration.py
@@ -8,8 +8,8 @@ import pytest
import yaml
from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow
-from specify_cli.workflows.overlays import WorkflowResolver
-from specify_cli.workflows.overlays.merge import ComposedStep
+from specify_cli.workflows.overlay import WorkflowResolver
+from specify_cli.workflows.overlay.merge import ComposedStep
def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:
diff --git a/tests/workflows/test_slot_step.py b/tests/workflows/test_slot_step.py
index 50416586a..457f929ce 100644
--- a/tests/workflows/test_slot_step.py
+++ b/tests/workflows/test_slot_step.py
@@ -11,8 +11,8 @@ import yaml
from specify_cli.workflows import BUILTIN_STEP_TYPES, get_step_type
from specify_cli.workflows.base import RunStatus, StepContext, StepStatus
from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine, validate_workflow
-from specify_cli.workflows.overlays import WorkflowResolver
-from specify_cli.workflows.steps.slot import SlotStep
+from specify_cli.workflows.overlay import WorkflowResolver
+from specify_cli.workflows.step.slot import SlotStep
def _workflow_data(steps: list[dict[str, object]]) -> dict[str, object]:
diff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.md
index 680cfc423..088baac22 100644
--- a/workflows/ARCHITECTURE.md
+++ b/workflows/ARCHITECTURE.md
@@ -79,7 +79,7 @@ When a `gate` step pauses execution, the engine persists `current_step_index` an
## Step Types
-The engine ships with 12 built-in step types, each in its own subpackage under `src/specify_cli/workflows/steps/`:
+The engine ships with 12 built-in step types, each in its own subpackage under `src/specify_cli/workflows/step/`:
| Type Key | Class | Purpose | Returns `next_steps`? |
|----------|-------|---------|-----------------------|