Skip to content

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

Add workflow step catalog β€” community-installable step types (#2394)

Copilotc52ccd7dc78c
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 3ee6358a0..9d9a869b7 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -2058,6 +2058,20 @@ workflow_catalog_app = typer.Typer(
)
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")
+
def _parse_input_values(input_values: list[str] | None) -> dict[str, Any]:
"""Parse repeated ``key=value`` CLI inputs into a dict.
@@ -2139,6 +2153,7 @@ def workflow_run(
),
):
"""Run a workflow from an installed ID or local YAML path."""
+ from .workflows import load_custom_steps
from .workflows.engine import WorkflowEngine
source_path = Path(source).expanduser()
@@ -2158,6 +2173,7 @@ def workflow_run(
else:
project_root = _require_specify_project()
+ load_custom_steps(project_root)
engine = WorkflowEngine(project_root)
if not json_output:
engine.on_step_start = lambda sid, label: console.print(f" \u25b8 [{sid}] {label} \u2026")
@@ -2227,9 +2243,11 @@ def workflow_resume(
),
):
"""Resume a paused or failed workflow run."""
+ from .workflows import load_custom_steps
from .workflows.engine import WorkflowEngine
project_root = _require_specify_project()
+ load_custom_steps(project_root)
engine = WorkflowEngine(project_root)
if not json_output:
engine.on_step_start = lambda sid, label: console.print(f" \u25b8 [{sid}] {label} \u2026")
@@ -2819,6 +2837,662 @@ def workflow_catalog_remove(
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 .workflows import STEP_REGISTRY
+ from .workflows.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 = meta.get("name", key)
+ version = meta.get("version", "?")
+ console.print(f" β€’ [bold]{name}[/bold] ({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 .workflows.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 .workflows 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)
+
+ step_yml_url = info.get("step_yml_url") or info.get("url")
+ if not step_yml_url:
+ console.print(f"[red]Error:[/red] Catalog entry for '{step_id}' has no URL")
+ 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 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)
+
+ from urllib.parse import urlparse
+ from specify_cli.authentication.http import open_url as _open_url
+
+ def _safe_fetch(url: str) -> bytes:
+ parsed = urlparse(url)
+ is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+ raise ValueError(f"Refusing to fetch from non-HTTPS URL: {url}")
+ if not parsed.hostname:
+ raise ValueError(f"Refusing to fetch from URL with no hostname: {url}")
+ with _open_url(url, timeout=30) as resp:
+ final_url = resp.geturl()
+ final_parsed = urlparse(final_url)
+ final_is_localhost = final_parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if final_parsed.scheme != "https" and not (
+ final_parsed.scheme == "http" and final_is_localhost
+ ):
+ raise ValueError(f"Redirect to non-HTTPS URL: {final_url}")
+ if not final_parsed.hostname:
+ raise ValueError(f"Redirect to URL with no hostname: {final_url}")
+ return resp.read()
+
+ _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)
+
+ # Validate step.yml
+ try:
+ import yaml as _yaml
+
+ meta = _yaml.safe_load(step_yml_content.decode("utf-8")) or {}
+ except Exception as exc:
+ console.print(f"[red]Error:[/red] Invalid step.yml: {exc}")
+ raise typer.Exit(1)
+
+ if 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)
+
+ if type_key != step_id:
+ console.print(
+ f"[red]Error:[/red] step.yml type_key ({type_key!r}) does not match "
+ f"catalog ID ({step_id!r})"
+ )
+ 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}"
+ )
+ 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.
+ 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 = {}
+ 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 rel_path in ("step.yml", "__init__.py"):
+ 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()
+ 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"
+ )
+ 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}"
+ )
+ raise typer.Exit(1)
+ try:
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ dest.write_bytes(file_content)
+ except OSError as exc:
+ console.print(
+ f"[red]Error:[/red] Failed to write extra file '{rel_path}': {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,
+ },
+ )
+ 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."
+ )
+
+
+@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 .workflows.catalog import StepRegistry, StepValidationError
+
+ 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.
+ 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
+ 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
+ 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}"
+ )
+ 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 .workflows.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]"
+ )
+ console.print(
+ f" [bold]{step.get('name', step.get('id', '?'))}[/bold]"
+ f" ({step.get('id', '?')}) v{step.get('version', '?')}{install_note}"
+ )
+ desc = step.get("description", "")
+ if desc:
+ console.print(f" {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 .workflows import STEP_REGISTRY
+ from .workflows.catalog import StepCatalog, StepCatalogError, StepRegistry
+
+ project_root = _require_specify_project()
+
+ 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]{step_id}[/bold cyan] [dim](built-in)[/dim]")
+ console.print(f" Type key: {step_id}")
+ console.print(" [green]Built-in step type[/green]")
+ return
+
+ if installed_meta:
+ console.print(
+ f"\n[bold cyan]{installed_meta.get('name', step_id)}[/bold cyan] ({step_id})"
+ )
+ console.print(f" Version: {installed_meta.get('version', '?')}")
+ if installed_meta.get("author"):
+ console.print(f" Author: {installed_meta['author']}")
+ if installed_meta.get("description"):
+ console.print(f" Description: {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:
+ console.print(
+ f"\n[bold cyan]{info.get('name', step_id)}[/bold cyan] ({step_id})"
+ )
+ console.print(f" Version: {info.get('version', '?')}")
+ if info.get("author"):
+ console.print(f" Author: {info['author']}")
+ if info.get("description"):
+ console.print(f" Description: {info['description']}")
+ console.print(" [yellow]Not installed[/yellow]")
+ console.print(
+ f"\n Install with: [cyan]specify workflow step add {step_id}[/cyan]"
+ )
+ else:
+ console.print(f"[red]Error:[/red] Step type '{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 .workflows.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]"
+ )
+ console.print(f" [{i}] [bold]{cfg['name']}[/bold] β€” {install_status}")
+ console.print(f" {cfg['url']}")
+ if cfg.get("description"):
+ console.print(f" [dim]{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 = typer.Option(None, "--name", help="Catalog name"),
+):
+ """Add a step catalog source."""
+ from .workflows.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 .workflows.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")
+
+
def main():
# On Windows the default stdout/stderr code page (e.g. cp1252) cannot encode
# the Rich banner and box-drawing glyphs, so the CLI crashes with
diff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.py
index 13782f620..eac21a668 100644
--- a/src/specify_cli/workflows/__init__.py
+++ b/src/specify_cli/workflows/__init__.py
@@ -7,10 +7,12 @@ Provides:
- ``STEP_REGISTRY`` β€” maps ``type_key`` to ``StepBase`` subclass instances.
- ``WorkflowEngine`` β€” orchestrator that loads, validates, and executes
workflow YAML definitions.
+- ``load_custom_steps`` β€” loads community-installed step types into STEP_REGISTRY.
"""
from __future__ import annotations
+from pathlib import Path
from typing import TYPE_CHECKING
if TYPE_CHECKING:
@@ -66,3 +68,134 @@ def _register_builtin_steps() -> None:
_register_builtin_steps()
+
+
+def load_custom_steps(project_root: Path) -> list[str]:
+ """Load community-installed custom step types into STEP_REGISTRY.
+
+ Scans ``.specify/workflows/steps/`` for installed step packages.
+ Each valid package must contain ``step.yml`` (with a ``step.type_key``
+ field) and ``__init__.py`` (a ``StepBase`` subclass).
+
+ Returns a list of type_keys that were successfully loaded.
+ Silently skips packages that fail to import or validate.
+ """
+ import hashlib as _hashlib
+ import importlib.util as _importlib_util
+ import re as _re
+ import sys as _sys
+
+ steps_dir = Path(project_root) / ".specify" / "workflows" / "steps"
+
+ # Defense-in-depth: refuse to execute step code from a symlinked
+ # parent directory under .specify/workflows/steps, which could redirect
+ # the import outside the project root and bypass the install-time
+ # symlink guard. Check symlinks *before* is_dir() since the latter
+ # follows symlinks and would stat an external target.
+ _current = Path(project_root)
+ for _part in (".specify", "workflows", "steps"):
+ _current = _current / _part
+ if _current.is_symlink():
+ return []
+
+ if not steps_dir.is_dir():
+ return []
+
+ loaded: list[str] = []
+ for step_dir in steps_dir.iterdir():
+ # Check symlinks before is_dir() since the latter follows symlinks
+ # and would stat an external target through a symlinked directory.
+ if step_dir.is_symlink():
+ continue
+ if not step_dir.is_dir():
+ continue
+ step_yml = step_dir / "step.yml"
+ init_py = step_dir / "__init__.py"
+ if step_yml.is_symlink() or init_py.is_symlink():
+ continue
+ if not step_yml.is_file() or not init_py.is_file():
+ continue
+
+ try:
+ import yaml as _yaml
+
+ meta = _yaml.safe_load(step_yml.read_text(encoding="utf-8")) or {}
+ step_meta = meta.get("step", {})
+ type_key = step_meta.get("type_key", "")
+ if not type_key:
+ continue
+
+ # Skip if already registered (e.g. built-in or previously loaded)
+ if type_key in STEP_REGISTRY:
+ continue
+
+ # Sanitize type_key so the synthetic module name is a valid identifier
+ # (e.g. "test-custom" β†’ "_speckit_custom_step_test_custom_<hash>").
+ # The 8-char SHA-256 hash of the original type_key makes the name
+ # collision-resistant when different type_keys produce the same
+ # sanitized form (e.g. "a-b" and "a_b" both sanitize to "a_b" but
+ # have different hashes).
+ safe_key = _re.sub(r"[^A-Za-z0-9_]", "_", type_key)
+ key_hash = _hashlib.sha256(type_key.encode()).hexdigest()[:8]
+ module_name = f"_speckit_custom_step_{safe_key}_{key_hash}"
+
+ # Treat the step directory as a proper package so that relative
+ # imports inside the step (e.g. ``from .helpers import …``) work.
+ spec = _importlib_util.spec_from_file_location(
+ module_name,
+ init_py,
+ submodule_search_locations=[str(step_dir)],
+ )
+ if spec is None or spec.loader is None:
+ continue
+ module = _importlib_util.module_from_spec(spec)
+ module.__package__ = module_name
+ # Register before exec so relative imports resolve correctly.
+ _sys.modules[module_name] = module
+ registered = False
+ try:
+ spec.loader.exec_module(module) # type: ignore[union-attr]
+
+ # Find the StepBase subclass in the module
+ from .base import StepBase as _StepBase
+
+ step_class = None
+ for attr_name in dir(module):
+ attr = getattr(module, attr_name)
+ try:
+ if (
+ isinstance(attr, type)
+ and issubclass(attr, _StepBase)
+ and attr is not _StepBase
+ and getattr(attr, "type_key", "") == type_key
+ ):
+ step_class = attr
+ break
+ except TypeError:
+ continue
+
+ if step_class is None:
+ continue
+
+ _register_step(step_class())
+ loaded.append(type_key)
+ registered = True
+ finally:
+ # If the step wasn't successfully registered (failed import,
+ # no matching StepBase subclass, or registration error), remove
+ # the synthetic module β€” and any submodules loaded via relative
+ # imports (e.g. ``from .helpers import …``) β€” from sys.modules so
+ # a broken/skipped step package leaves no lingering import state
+ # behind.
+ if not registered:
+ _sys.modules.pop(module_name, None)
+ submodule_prefix = module_name + "."
+ for _mod_key in [
+ k for k in _sys.modules if k.startswith(submodule_prefix)
+ ]:
+ _sys.modules.pop(_mod_key, None)
+ except Exception: # noqa: BLE001
+ # Silently skip broken step packages at load time
+ continue
+
+ return loaded
diff --git a/src/specify_cli/workflows/catalog.py b/src/specify_cli/workflows/catalog.py
index 213b443e3..97bf58a04 100644
--- a/src/specify_cli/workflows/catalog.py
+++ b/src/specify_cli/workflows/catalog.py
@@ -1,9 +1,10 @@
-"""Workflow catalog β€” discovery, install, and management of workflows.
+"""Workflow catalog β€” discovery, install, and management of workflows and step types.
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
"""
@@ -165,7 +166,7 @@ class WorkflowCatalog:
f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
"HTTP is only allowed for localhost."
)
- if not parsed.netloc:
+ if not parsed.hostname:
raise WorkflowValidationError(
"Catalog URL must be a valid URL with a host."
)
@@ -181,6 +182,11 @@ class WorkflowCatalog:
except (yaml.YAMLError, OSError, UnicodeError) as exc:
raise WorkflowValidationError(
f"Failed to read catalog config {config_path}: {exc}"
+ ) from exc
+ if not isinstance(data, dict):
+ raise WorkflowValidationError(
+ f"Invalid catalog config: expected a mapping, "
+ f"got {type(data).__name__}"
)
catalogs_data = data.get("catalogs", [])
if not catalogs_data:
@@ -302,9 +308,9 @@ class WorkflowCatalog:
try:
with open(meta_file, encoding="utf-8") as f:
meta = json.load(f)
- fetched_at = meta.get("fetched_at", 0)
+ fetched_at = float(meta.get("fetched_at", 0))
return (time.time() - fetched_at) < self.CACHE_DURATION
- except (json.JSONDecodeError, OSError):
+ except (json.JSONDecodeError, OSError, TypeError, ValueError):
return False
def _fetch_single_catalog(
@@ -318,6 +324,7 @@ class WorkflowCatalog:
with open(cache_file, encoding="utf-8") as f:
return json.load(f)
except (json.JSONDecodeError, OSError):
+ # Ignore invalid/unreadable cache and fall back to fetching from source.
pass
# Fetch from URL β€” validate scheme before opening and after redirects
@@ -333,6 +340,10 @@ class WorkflowCatalog:
raise WorkflowCatalogError(
f"Refusing to fetch catalog from non-HTTPS URL: {url}"
)
+ if not parsed.hostname:
+ raise WorkflowCatalogError(
+ f"Refusing to fetch catalog from URL with no hostname: {url}"
+ )
_validate_catalog_url(entry.url)
@@ -347,6 +358,7 @@ class WorkflowCatalog:
with open(cache_file, encoding="utf-8") as f:
return json.load(f)
except (json.JSONDecodeError, ValueError, OSError):
+ # Stale-cache read failed; let the original fetch error propagate.
pass
raise WorkflowCatalogError(
f"Failed to fetch catalog from {entry.url}: {exc}"
@@ -358,11 +370,14 @@ class WorkflowCatalog:
)
# Write cache
- 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)
+ 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
@@ -468,7 +483,14 @@ class WorkflowCatalog:
data: dict[str, Any] = {"catalogs": []}
if config_path.exists():
- raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ try:
+ raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise WorkflowValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
+ if raw is None:
+ raw = {"catalogs": []}
if not isinstance(raw, dict):
raise WorkflowValidationError(
"Catalog config file is corrupted (expected a mapping)."
@@ -487,9 +509,21 @@ class WorkflowCatalog:
f"Catalog URL already configured: {url}"
)
- # Derive priority from the highest existing priority + 1
+ # Derive priority from the highest existing priority + 1.
+ # Coerce existing priorities to int with a safe fallback so a user-edited
+ # workflow-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):
+ return 0
+
max_priority = max(
- (cat.get("priority", 0) for cat in catalogs if isinstance(cat, dict)),
+ (
+ _coerce_priority(cat.get("priority", 0))
+ for cat in catalogs
+ if isinstance(cat, dict)
+ ),
default=0,
)
catalogs.append(
@@ -503,9 +537,14 @@ class WorkflowCatalog:
)
data["catalogs"] = catalogs
- 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)
+ 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 WorkflowValidationError(
+ 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."""
@@ -513,7 +552,12 @@ class WorkflowCatalog:
if not config_path.exists():
raise WorkflowValidationError("No catalog config file found.")
- data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+ try:
+ data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise WorkflowValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
if not isinstance(data, dict):
raise WorkflowValidationError(
"Catalog config file is corrupted (expected a mapping)."
@@ -532,8 +576,623 @@ class WorkflowCatalog:
removed = catalogs.pop(index)
data["catalogs"] = catalogs
- with open(config_path, "w", encoding="utf-8") as f:
- yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+ 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 WorkflowValidationError(
+ 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}"
+
+
+# ---------------------------------------------------------------------------
+# 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
+
+ existing = self.data["steps"].get(step_id, {})
+ 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
+
+ parsed = urlparse(url)
+ is_localhost = parsed.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 parsed.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")) or {}
+ except (yaml.YAMLError, OSError, UnicodeError) as exc:
+ raise StepValidationError(
+ f"Failed to read catalog config {config_path}: {exc}"
+ ) from exc
+ 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 not catalogs_data:
+ 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__}"
+ )
+
+ 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)
+ try:
+ priority = int(item.get("priority", idx + 1))
+ except (TypeError, ValueError):
+ raise StepValidationError(
+ f"Invalid priority for catalog "
+ f"'{item.get('name', idx + 1)}': "
+ f"expected integer, got {item.get('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)
+ 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 (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:
+ parsed = urlparse(url)
+ is_localhost = parsed.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 parsed.hostname:
+ raise StepCatalogError(
+ f"Refusing to fetch catalog from URL with no hostname: {url}"
+ )
+
+ _validate_url(entry.url)
+
+ try:
+ with _open_url(entry.url, timeout=30) as resp:
+ _validate_url(resp.geturl())
+ data = json.loads(resp.read().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")) or {}
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise StepValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
+ if 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):
+ 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")) or {}
+ except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc:
+ raise StepValidationError(
+ f"Catalog config file is unreadable or malformed: {exc}"
+ ) from exc
+ if 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}")
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 36b105fd4..2a497dcb5 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -32,7 +32,10 @@ def temp_dir():
"""Create a temporary directory for tests."""
tmpdir = tempfile.mkdtemp()
yield Path(tmpdir)
- shutil.rmtree(tmpdir)
+ # On Windows, file handles from dynamic imports or registry access may
+ # still be held briefly after the test. Use ignore_errors to avoid
+ # flaky teardown failures (WinError 32).
+ shutil.rmtree(tmpdir, ignore_errors=(sys.platform == "win32"))
@pytest.fixture
@@ -3313,9 +3316,11 @@ class TestWorkflowRegistry:
class TestWorkflowCatalog:
"""Test WorkflowCatalog catalog resolution."""
- def test_default_catalogs(self, project_dir):
+ def test_default_catalogs(self, project_dir, monkeypatch):
from specify_cli.workflows.catalog import WorkflowCatalog
+ monkeypatch.setattr(Path, "home", lambda: project_dir)
+ monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False)
catalog = WorkflowCatalog(project_dir)
entries = catalog.get_active_catalogs()
assert len(entries) == 2
@@ -3417,6 +3422,78 @@ class TestWorkflowCatalog:
assert configs[0]["name"] == "default"
assert isinstance(configs[0]["install_allowed"], bool)
+ def test_load_catalog_config_non_dict_yaml_raises(self, project_dir):
+ """A YAML catalog config that is a list (not a mapping) must raise WorkflowValidationError."""
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
+
+ config_path = project_dir / ".specify" / "workflow-catalogs.yml"
+ config_path.write_text("- item1\n- item2\n", encoding="utf-8")
+
+ catalog = WorkflowCatalog(project_dir)
+ with pytest.raises(WorkflowValidationError, match="expected a mapping"):
+ catalog.get_active_catalogs()
+
+ def test_add_catalog_malformed_yaml_raises(self, project_dir):
+ """A malformed YAML config file must raise WorkflowValidationError when adding a catalog."""
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
+
+ config_path = project_dir / ".specify" / "workflow-catalogs.yml"
+ config_path.write_text(": invalid: yaml: {\n", encoding="utf-8")
+
+ catalog = WorkflowCatalog(project_dir)
+ with pytest.raises(WorkflowValidationError, match="unreadable or malformed"):
+ catalog.add_catalog("https://example.com/new.json")
+
+ def test_remove_catalog_malformed_yaml_raises(self, project_dir):
+ """A malformed YAML config file must raise WorkflowValidationError when removing a catalog."""
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
+
+ catalog = WorkflowCatalog(project_dir)
+ catalog.add_catalog("https://example.com/c1.json", "first")
+
+ config_path = project_dir / ".specify" / "workflow-catalogs.yml"
+ config_path.write_text(": bad: yaml: {\n", encoding="utf-8")
+
+ with pytest.raises(WorkflowValidationError, match="unreadable or malformed"):
+ catalog.remove_catalog(0)
+
+ def test_add_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
+ """An OSError on write must be wrapped as WorkflowValidationError."""
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
+ import builtins
+
+ catalog = WorkflowCatalog(project_dir)
+ config_path = project_dir / ".specify" / "workflow-catalogs.yml"
+ real_open = builtins.open
+
+ def _raising_open(file, mode="r", *args, **kwargs):
+ if Path(file) == config_path and "w" in mode:
+ raise OSError("simulated write failure")
+ return real_open(file, mode, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "open", _raising_open)
+ with pytest.raises(WorkflowValidationError, match="Failed to write catalog config"):
+ catalog.add_catalog("https://example.com/new-catalog.json", "my-catalog")
+
+ def test_remove_catalog_wraps_write_oserror(self, project_dir, monkeypatch):
+ """An OSError on write must be wrapped as WorkflowValidationError."""
+ from specify_cli.workflows.catalog import WorkflowCatalog, WorkflowValidationError
+ import builtins
+
+ catalog = WorkflowCatalog(project_dir)
+ catalog.add_catalog("https://example.com/c1.json", "first")
+ config_path = project_dir / ".specify" / "workflow-catalogs.yml"
+ real_open = builtins.open
+
+ def _raising_open(file, mode="r", *args, **kwargs):
+ if Path(file) == config_path and "w" in mode:
+ raise OSError("simulated write failure")
+ return real_open(file, mode, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "open", _raising_open)
+ with pytest.raises(WorkflowValidationError, match="Failed to write catalog config"):
+ catalog.remove_catalog(0)
+
# ===== Integration Test =====
@@ -3513,6 +3590,933 @@ steps:
assert "do-specify" not in state.step_results
+# ===== Step Registry Tests =====
+
+class TestStepRegistryCustom:
+ """Test StepRegistry operations for custom step types."""
+
+ def test_add_and_get(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry = StepRegistry(project_dir)
+ registry.add("deploy", {"name": "Deploy", "version": "1.0.0", "type_key": "deploy"})
+
+ entry = registry.get("deploy")
+ assert entry is not None
+ assert entry["name"] == "Deploy"
+ assert "installed_at" in entry
+
+ def test_add_does_not_mutate_input_metadata(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry = StepRegistry(project_dir)
+ metadata = {
+ "name": "Deploy",
+ "type_key": "deploy",
+ "nested": {"key": "original"},
+ }
+
+ registry.add("deploy", metadata)
+
+ assert "installed_at" not in metadata
+ assert "updated_at" not in metadata
+ metadata["nested"]["key"] = "changed-after-add"
+ assert registry.get("deploy")["nested"]["key"] == "original"
+
+ def test_remove(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry = StepRegistry(project_dir)
+ registry.add("deploy", {"name": "Deploy", "type_key": "deploy"})
+ assert registry.is_installed("deploy")
+
+ registry.remove("deploy")
+ assert not registry.is_installed("deploy")
+
+ def test_remove_missing_returns_false(self, project_dir):
+ from specify_cli.workflows.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
+
+ registry = StepRegistry(project_dir)
+ registry.add("step-a", {"name": "A", "type_key": "step-a"})
+ registry.add("step-b", {"name": "B", "type_key": "step-b"})
+
+ installed = registry.list()
+ assert "step-a" in installed
+ assert "step-b" in installed
+
+ def test_is_installed(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry = StepRegistry(project_dir)
+ assert not registry.is_installed("missing")
+
+ registry.add("exists", {"name": "Exists", "type_key": "exists"})
+ assert registry.is_installed("exists")
+
+ def test_persistence(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry1 = StepRegistry(project_dir)
+ registry1.add("deploy", {"name": "Deploy", "type_key": "deploy"})
+
+ registry2 = StepRegistry(project_dir)
+ assert registry2.is_installed("deploy")
+
+ def test_corrupted_registry_resets(self, project_dir):
+ from specify_cli.workflows.catalog import StepRegistry
+
+ registry = StepRegistry(project_dir)
+ registry.steps_dir.mkdir(parents=True, exist_ok=True)
+ registry.registry_path.write_text("not json", encoding="utf-8")
+
+ # Loading again should reset
+ registry2 = StepRegistry(project_dir)
+ assert registry2.list() == {}
+
+ 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
+ import json as _json
+
+ registry = StepRegistry(project_dir)
+ registry.steps_dir.mkdir(parents=True, exist_ok=True)
+ # Valid JSON but 'steps' is not a dict
+ registry.registry_path.write_text(
+ _json.dumps({"schema_version": "1.0", "steps": "bad"}),
+ encoding="utf-8",
+ )
+
+ registry2 = StepRegistry(project_dir)
+ # Should be safe to call add/get without KeyError
+ assert registry2.list() == {}
+ registry2.add("deploy", {"name": "Deploy", "type_key": "deploy"})
+ assert registry2.is_installed("deploy")
+
+ @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
+ import json as _json
+
+ registry = StepRegistry(project_dir)
+ registry.steps_dir.mkdir(parents=True, exist_ok=True)
+ # Write valid registry first
+ registry.registry_path.write_text(
+ _json.dumps({"schema_version": "1.0", "steps": {"existing": {}}}),
+ encoding="utf-8",
+ )
+ # Make it unreadable
+ registry.registry_path.chmod(0o000)
+ try:
+ registry2 = StepRegistry(project_dir)
+ assert registry2.list() == {}
+ finally:
+ registry.registry_path.chmod(0o644)
+
+ # After restoring permissions the registry is fully functional
+ registry2.add("deploy", {"name": "Deploy", "type_key": "deploy"})
+ assert registry2.is_installed("deploy")
+
+ @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
+ import json as _json
+
+ outside = project_dir.parent / "outside-steps"
+ outside.mkdir(parents=True, exist_ok=True)
+ (outside / "step-registry.json").write_text(
+ _json.dumps({"schema_version": "1.0", "steps": {"evil": {}}}),
+ encoding="utf-8",
+ )
+ steps_link = project_dir / ".specify" / "workflows" / "steps"
+ steps_link.symlink_to(outside, target_is_directory=True)
+
+ registry = StepRegistry(project_dir)
+ assert registry.list() == {}
+
+ @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
+
+ outside = project_dir.parent / "outside-steps-save"
+ outside.mkdir(parents=True, exist_ok=True)
+ steps_link = project_dir / ".specify" / "workflows" / "steps"
+ steps_link.symlink_to(outside, target_is_directory=True)
+
+ registry = StepRegistry(project_dir)
+ with pytest.raises(StepValidationError, match="symlinked path"):
+ registry.save()
+
+
+# ===== Step Catalog Tests =====
+
+class TestStepCatalog:
+ """Test StepCatalog catalog resolution."""
+
+ def test_default_catalogs(self, project_dir, monkeypatch):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ monkeypatch.setattr(Path, "home", lambda: project_dir)
+ monkeypatch.delenv("SPECKIT_STEP_CATALOG_URL", raising=False)
+ catalog = StepCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+ assert len(entries) == 2
+ assert entries[0].name == "default"
+ assert entries[1].name == "community"
+
+ def test_env_var_override(self, project_dir, monkeypatch):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ monkeypatch.setenv("SPECKIT_STEP_CATALOG_URL", "https://example.com/step-catalog.json")
+ catalog = StepCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+ assert len(entries) == 1
+ assert entries[0].name == "env-override"
+ 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
+
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ config_path.write_text(yaml.dump({
+ "catalogs": [{
+ "name": "custom",
+ "url": "https://example.com/step-catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ }]
+ }))
+
+ catalog = StepCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+ assert len(entries) == 1
+ assert entries[0].name == "custom"
+
+ def test_validate_url_http_rejected(self, project_dir):
+ from specify_cli.workflows.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
+
+ catalog = StepCatalog(project_dir)
+ # Should not raise
+ catalog._validate_catalog_url("http://localhost:8080/step-catalog.json")
+
+ def test_add_catalog(self, project_dir):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/new-steps.json", "my-steps")
+
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ assert config_path.exists()
+ data = yaml.safe_load(config_path.read_text())
+ assert len(data["catalogs"]) == 1
+ assert data["catalogs"][0]["url"] == "https://example.com/new-steps.json"
+
+ 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
+
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ config_path.write_text("", encoding="utf-8")
+
+ catalog = StepCatalog(project_dir)
+ # Should not raise StepValidationError "corrupted"
+ catalog.add_catalog("https://example.com/steps.json", "my-steps")
+
+ data = yaml.safe_load(config_path.read_text())
+ assert len(data["catalogs"]) == 1
+ assert data["catalogs"][0]["url"] == "https://example.com/steps.json"
+
+ def test_add_catalog_duplicate_rejected(self, project_dir):
+ from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/steps.json")
+
+ with pytest.raises(StepValidationError, match="already configured"):
+ catalog.add_catalog("https://example.com/steps.json")
+
+ def test_remove_catalog(self, project_dir):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/s1.json", "first")
+ catalog.add_catalog("https://example.com/s2.json", "second")
+
+ removed = catalog.remove_catalog(0)
+ assert removed == "first"
+
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ data = yaml.safe_load(config_path.read_text())
+ assert len(data["catalogs"]) == 1
+
+ def test_remove_catalog_invalid_index(self, project_dir):
+ from specify_cli.workflows.catalog import StepCatalog, StepValidationError
+
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/s1.json")
+
+ with pytest.raises(StepValidationError, match="out of range"):
+ catalog.remove_catalog(5)
+
+ def test_remove_catalog_no_config(self, project_dir):
+ from specify_cli.workflows.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
+ import builtins
+
+ catalog = StepCatalog(project_dir)
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ real_open = builtins.open
+
+ def _raising_open(file, mode="r", *args, **kwargs):
+ if Path(file) == config_path and "w" in mode:
+ raise OSError("simulated write failure")
+ return real_open(file, mode, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "open", _raising_open)
+ with pytest.raises(StepValidationError, match="Failed to write catalog config"):
+ 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
+ import builtins
+
+ catalog = StepCatalog(project_dir)
+ catalog.add_catalog("https://example.com/s1.json", "first")
+ config_path = project_dir / ".specify" / "step-catalogs.yml"
+ real_open = builtins.open
+
+ def _raising_open(file, mode="r", *args, **kwargs):
+ if Path(file) == config_path and "w" in mode:
+ raise OSError("simulated write failure")
+ return real_open(file, mode, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "open", _raising_open)
+ with pytest.raises(StepValidationError, match="Failed to write catalog config"):
+ catalog.remove_catalog(0)
+
+ def test_get_catalog_configs(self, project_dir):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ catalog = StepCatalog(project_dir)
+ configs = catalog.get_catalog_configs()
+ assert len(configs) == 2
+ assert configs[0]["name"] == "default"
+ assert isinstance(configs[0]["install_allowed"], bool)
+
+ def test_search_with_mock_catalog(self, project_dir, monkeypatch):
+ from specify_cli.workflows.catalog import StepCatalog
+
+ mock_data = {
+ "schema_version": "1.0",
+ "steps": {
+ "deploy": {
+ "id": "deploy",
+ "name": "Deploy Step",
+ "description": "Deploy to production",
+ "version": "1.0.0",
+ },
+ "notify": {
+ "id": "notify",
+ "name": "Notify Step",
+ "description": "Send notifications",
+ "version": "1.0.0",
+ },
+ },
+ }
+
+ catalog = StepCatalog(project_dir)
+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
+ "deploy": dict(mock_data["steps"]["deploy"], _catalog_name="test", _install_allowed=True),
+ "notify": dict(mock_data["steps"]["notify"], _catalog_name="test", _install_allowed=True),
+ })
+
+ results = catalog.search()
+ assert len(results) == 2
+
+ results = catalog.search(query="deploy")
+ assert len(results) == 1
+ assert results[0]["id"] == "deploy"
+
+ 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
+
+ catalog = StepCatalog(project_dir)
+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
+ "42": {
+ "id": 42,
+ "name": None,
+ "description": 99,
+ "_catalog_name": "test",
+ "_install_allowed": True,
+ },
+ })
+
+ results = catalog.search()
+ assert len(results) == 1
+
+ results = catalog.search(query="42")
+ assert len(results) == 1
+
+ results = catalog.search(query="missing")
+ assert len(results) == 0
+
+ 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
+
+ catalog = StepCatalog(project_dir)
+ entry = StepCatalogEntry(
+ name="test",
+ url="https://example.com/steps.json",
+ priority=1,
+ install_allowed=True,
+ )
+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: [entry])
+ monkeypatch.setattr(
+ catalog,
+ "_fetch_single_catalog",
+ lambda _entry, _force_refresh=False: {
+ "steps": [{"id": 42, "name": "Integer ID"}]
+ },
+ )
+
+ merged = catalog._get_merged_steps()
+ assert "42" in merged
+ assert 42 not in merged
+ assert merged["42"]["id"] == "42"
+
+ 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
+
+ catalog = StepCatalog(project_dir)
+ monkeypatch.setattr(catalog, "_get_merged_steps", lambda **kw: {
+ "deploy": {
+ "id": "deploy",
+ "name": "Deploy Step",
+ "version": "1.0.0",
+ "_catalog_name": "test",
+ "_install_allowed": True,
+ },
+ })
+
+ info = catalog.get_step_info("deploy")
+ assert info is not None
+ assert info["name"] == "Deploy Step"
+
+ missing = catalog.get_step_info("nonexistent")
+ assert missing is None
+
+
+# ===== Load Custom Steps Tests =====
+
+class TestLoadCustomSteps:
+ """Test dynamic loading of custom step types from the filesystem."""
+
+ def test_empty_steps_dir(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ loaded = load_custom_steps(project_dir)
+ assert loaded == []
+
+ def test_no_steps_dir(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ # .specify/workflows/steps does not exist
+ loaded = load_custom_steps(project_dir)
+ assert loaded == []
+
+ def test_load_valid_custom_step(self, project_dir):
+ from specify_cli.workflows import load_custom_steps, STEP_REGISTRY
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "test-custom"
+ step_dir.mkdir(parents=True)
+
+ step_yml = """
+schema_version: "1.0"
+step:
+ type_key: "test-custom"
+ name: "Test Custom Step"
+ version: "1.0.0"
+ author: "test"
+ description: "A test custom step"
+"""
+ (step_dir / "step.yml").write_text(step_yml, encoding="utf-8")
+
+ init_py = """
+from specify_cli.workflows.base import StepBase, StepResult
+
+class TestCustomStep(StepBase):
+ type_key = "test-custom"
+
+ def execute(self, config, context):
+ return StepResult()
+"""
+ (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")
+
+ loaded = load_custom_steps(project_dir)
+ assert "test-custom" in loaded
+ assert "test-custom" in STEP_REGISTRY
+
+ def test_skip_missing_step_yml(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "__init__.py").write_text("# no step.yml", encoding="utf-8")
+
+ loaded = load_custom_steps(project_dir)
+ assert "bad-step" not in loaded
+
+ def test_skip_missing_init_py(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-step2"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: bad-step2\n", encoding="utf-8"
+ )
+
+ loaded = load_custom_steps(project_dir)
+ assert "bad-step2" not in loaded
+
+ @pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")
+ def test_skip_symlinked_step_files(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "bad-symlinked-files"
+ step_dir.mkdir(parents=True)
+
+ outside = project_dir.parent / "outside-step-files"
+ outside.mkdir(parents=True, exist_ok=True)
+ step_yml_target = outside / "step.yml"
+ step_yml_target.write_text("step:\n type_key: bad-symlinked-files\n", encoding="utf-8")
+ init_target = outside / "__init__.py"
+ init_target.write_text("# external code", encoding="utf-8")
+
+ (step_dir / "step.yml").symlink_to(step_yml_target)
+ (step_dir / "__init__.py").symlink_to(init_target)
+
+ loaded = load_custom_steps(project_dir)
+ assert "bad-symlinked-files" not in loaded
+
+ def test_skip_already_registered(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ # "command" is already registered as a built-in step
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "command"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: command\n", encoding="utf-8"
+ )
+ (step_dir / "__init__.py").write_text("", encoding="utf-8")
+
+ # Should not raise KeyError; just skip
+ loaded = load_custom_steps(project_dir)
+ assert "command" not in loaded
+
+ def test_skip_broken_init_py(self, project_dir):
+ from specify_cli.workflows import load_custom_steps
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "broken-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: broken-step\n", encoding="utf-8"
+ )
+ (step_dir / "__init__.py").write_text(
+ "raise RuntimeError('broken')", encoding="utf-8"
+ )
+
+ # Should not propagate exception
+ loaded = load_custom_steps(project_dir)
+ assert "broken-step" not in loaded
+
+ def test_module_name_sanitized_for_hyphenated_type_key(self, project_dir):
+ """type_key values with hyphens produce valid Python module identifiers."""
+ import hashlib
+ import sys
+ from specify_cli.workflows import load_custom_steps, STEP_REGISTRY
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "my-hyphen-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: my-hyphen-step\n name: Hyphen Step\n",
+ encoding="utf-8",
+ )
+
+ init_py = """
+from specify_cli.workflows.base import StepBase, StepResult
+
+class HyphenStep(StepBase):
+ type_key = "my-hyphen-step"
+
+ def execute(self, config, context):
+ return StepResult()
+"""
+ (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")
+
+ loaded = load_custom_steps(project_dir)
+ assert "my-hyphen-step" in loaded
+ assert "my-hyphen-step" in STEP_REGISTRY
+ # Synthetic module name must be a valid identifier (hyphens β†’ underscores)
+ # and include a collision-resistant hash suffix.
+ key_hash = hashlib.sha256(b"my-hyphen-step").hexdigest()[:8]
+ module_name = f"_speckit_custom_step_my_hyphen_step_{key_hash}"
+ assert module_name in sys.modules
+
+ def test_package_relative_import(self, project_dir):
+ """Steps can use relative imports to access sibling modules."""
+ import hashlib
+ import sys
+ from specify_cli.workflows import load_custom_steps, STEP_REGISTRY
+
+ step_dir = project_dir / ".specify" / "workflows" / "steps" / "pkg-step"
+ step_dir.mkdir(parents=True)
+ (step_dir / "step.yml").write_text(
+ "step:\n type_key: pkg-step\n name: Package Step\n",
+ encoding="utf-8",
+ )
+ # Helper module that the step will import relatively
+ (step_dir / "helpers.py").write_text(
+ "HELPER_VALUE = 'hello'\n", encoding="utf-8"
+ )
+ init_py = """
+from specify_cli.workflows.base import StepBase, StepResult
+from .helpers import HELPER_VALUE
+
+class PkgStep(StepBase):
+ type_key = "pkg-step"
+ helper = HELPER_VALUE
+
+ def execute(self, config, context):
+ return StepResult()
+"""
+ (step_dir / "__init__.py").write_text(init_py, encoding="utf-8")
+
+ loaded = load_custom_steps(project_dir)
+ assert "pkg-step" in loaded
+ assert "pkg-step" in STEP_REGISTRY
+ # Verify the relative import actually resolved; module name includes hash suffix.
+ key_hash = hashlib.sha256(b"pkg-step").hexdigest()[:8]
+ module_name = f"_speckit_custom_step_pkg_step_{key_hash}"
+ assert module_name in sys.modules
+ assert sys.modules[module_name].PkgStep.helper == "hello"
+
+ def test_module_name_collision_resistance(self, project_dir):
+ """'a-b' and 'a_b' produce different module names despite the same sanitized form."""
+ import hashlib
+
+ # Simulate the module name generation for two type_keys that sanitize the same way
+ def make_module_name(type_key: str) -> str:
+ import re
+ safe_key = re.sub(r"[^A-Za-z0-9_]", "_", type_key)
+ key_hash = hashlib.sha256(type_key.encode()).hexdigest()[:8]
+ return f"_speckit_custom_step_{safe_key}_{key_hash}"
+
+ name_a = make_module_name("a-b")
+ name_b = make_module_name("a_b")
+ assert name_a != name_b, "Module names for 'a-b' and 'a_b' must differ"
+
+
+# ===== 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 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_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):
+ 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):
+ 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):
+ 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):
+ 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):
+ 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):
+ 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."""
diff --git a/workflows/step-catalog.community.json b/workflows/step-catalog.community.json
new file mode 100644
index 000000000..50a45049f
--- /dev/null
+++ b/workflows/step-catalog.community.json
@@ -0,0 +1,6 @@
+{
+ "schema_version": "1.0",
+ "updated_at": "2026-04-28T00:00:00Z",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/step-catalog.community.json",
+ "steps": {}
+}
diff --git a/workflows/step-catalog.json b/workflows/step-catalog.json
new file mode 100644
index 000000000..e109bf4ed
--- /dev/null
+++ b/workflows/step-catalog.json
@@ -0,0 +1,6 @@
+{
+ "schema_version": "1.0",
+ "updated_at": "2026-04-28T00:00:00Z",
+ "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/workflows/step-catalog.json",
+ "steps": {}
+}