💫 Toolkit to help you get started with SDD or any other process!
"""Command handler for ``specify workflow add``."""
from __future__ import annotations
from typing import Annotated
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())
def _prepare_workflow_add(
project_root: cli.Path, source: str, *, dev: bool, from_url: str | None,
version: str | None, selected_catalog: bool = False,
) -> cli.Path:
from . import load_custom_steps
if version is not None and (
dev or from_url is not None or (
not selected_catalog and (
source.startswith(("http://", "https://"))
or cli.Path(source).exists()
)
)
):
cli.console.print(
"[red]Error:[/red] --version requires a workflow ID from a catalog."
)
raise cli.typer.Exit(1)
if version is not None or selected_catalog:
cli._validate_workflow_id_or_exit(source)
load_custom_steps(project_root)
cli._open_workflow_registry(project_root)
workflows_dir = project_root / ".specify" / "workflows"
if from_url is not None and not dev:
cli._validate_workflow_id_or_exit(source)
cli._reject_unsafe_dir(project_root / ".specify", ".specify")
cli._reject_unsafe_dir(workflows_dir, ".specify/workflows")
return workflows_dir
def _install_preselected_workflow(
workflow_id: str, *, version: str | None, selected_info: dict,
) -> None:
"""Install a bundle-selected release with the normal workflow preflights."""
project_root = cli._require_specify_project()
workflows_dir = _prepare_workflow_add(
project_root, workflow_id, dev=False, from_url=None,
version=version, selected_catalog=True,
)
cli._install_workflow_from_catalog(
project_root, workflows_dir, workflow_id,
requested_version=version, selected_info=selected_info,
)
@cli.workflow_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"
),
version: Annotated[
str | None, cli.typer.Option(help="Install an exact catalog release")
] = None,
):
"""Install a workflow from catalog, URL, or local path."""
from .engine import WorkflowDefinition
project_root = cli._require_specify_project()
workflows_dir = _prepare_workflow_add(
project_root, source, dev=dev, from_url=from_url, version=version,
)
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.authentication.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, requested_version=version
)