π« 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__.pyindex 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_stepsfrom .workflows.engine import WorkflowEnginesource_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_stepsfrom .workflows.engine import WorkflowEngineproject_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 withdiff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.pyindex 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 executesworkflow YAML definitions.+- ``load_custom_steps`` β loads community-installed step types into STEP_REGISTRY."""from __future__ import annotations+from pathlib import Pathfrom typing import TYPE_CHECKINGif 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 loadeddiff --git a/src/specify_cli/workflows/catalog.py b/src/specify_cli/workflows/catalog.pyindex 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 Falsedef _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.passraise 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 failsreturn 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 excdef 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 excif 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 excif isinstance(removed, dict):return removed.get("name", f"catalog-{index + 1}")diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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": {}+}