π« Toolkit to help you get started with SDD or any other process!
feat(workflows): WorkflowResolver standalone (PR 1) (#3557)
Markus Wondrakd6fa0460ed96
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex 1dfc5e690..70603618b 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -91,8 +91,192 @@ specify workflow add <source>| `--dev` | Install from a local workflow YAML file or directory || `--from <url>` | Install from a custom URL (`<source>` names the expected workflow ID) |-Installs a workflow from the catalog, a URL (HTTPS required), or a local file path.+Installs a workflow from the catalog, a URL (HTTPS required), a local YAML file, or a local directory containing `workflow.yml`.+## Workflow Overlays++Workflow overlays let a project extend or override an installed workflow without editing the installed `workflow.yml`. This keeps local customizations safe across `specify bundle update` or `specify workflow add` upgrades.++When `specify workflow run <workflow-id>` loads a workflow, the engine composes the base workflow with all enabled overlays for that workflow id. The result is validated like any other workflow definition.++### How Overlays Work++An overlay is a YAML file that declares a set of edit operations against the step list of a base workflow. Overlays use lower-wins precedence: higher priority numbers are applied first and lower numbers last. Equal-priority overlays are applied alphabetically by ID, with the last ID winning conflicts.++Project overlay files live at:++| Location | Purpose |+| --- | --- |+| `.specify/workflows/overlays/<id>/*.yml` | Project-local customizations |++### Overlay File Format++The recommended edit format uses the operation name as the key and the anchor step id as the value:++```yaml+id: "my-overlay"+extends: "speckit"+priority: 10+enabled: true+edits:+ - insert_after: implement+ step:+ id: run-lint+ type: shell+ run: "ruff check src/"++ - replace: review-spec+ step:+ id: review-spec+ type: gate+ message: "Review the generated spec (overlay override)."+ options: [approve, reject]+ on_reject: abort+```++The explicit form is also supported:++```yaml+edits:+ - operation: insert_after+ anchor: implement+ step:+ id: run-lint+ type: shell+ run: "ruff check src/"+```++#### Fields++| Field | Required | Description |+| --- | --- | --- |+| `id` | yes | Identifier for this overlay. Used in `specify workflow overlay *` commands. Must be lowercase letters, digits, and hyphens only; no dots, underscores, path separators, or `overlays`. |+| `extends` | yes | The workflow id this overlay applies to. Uses the same safe-id format as `id`; `overlays`, `runs`, and `steps` are reserved. |+| `priority` | no | Integer; defaults to `10`. Lower values have higher precedence and win conflicts. Missing or invalid values fall back to `10`. |+| `enabled` | no | Boolean. Defaults to `true`. Disabled overlays are ignored. |+| `edits` | yes | Non-empty list of edit operations. |++#### Edit Operations++| Operation | `step` required | Effect |+| --- | --- | --- |+| `insert_after` | yes | Insert `step` immediately after the anchor step. |+| `insert_before` | yes | Insert `step` immediately before the anchor step. |+| `replace` | yes | Replace the anchor step with `step`. |+| `remove` | no | Remove the anchor step from the list. |++The `anchor` is the `id` of a step in the base workflow. Anchors are resolved recursively inside `then`, `else`, `steps`, `cases.*`, and `default` blocks, so nested base steps can also be targeted. Fan-out templates (`step` inside a `fan-out` step) are **not** valid anchors.++Step ids must not contain `:` β that character is reserved for engine-generated nested ids.++### Overlay CLI Commands++#### Add a Project Overlay++```bash+specify workflow overlay add <path-to-overlay.yml> --priority <n>+```++Validates the overlay file and copies it to `.specify/workflows/overlays/<extends>/<id>.yml`. `--priority` defaults to `10` and overrides the `priority` field in the file.++#### List Overlays++```bash+specify workflow overlay list <workflow-id>+```++Shows all overlays for the workflow, ordered by resolver precedence. Disabled overlays are marked as disabled in the listing and are ignored during workflow resolution.++#### Change Priority++```bash+specify workflow overlay set-priority <workflow-id> <overlay-id> <n>+```++#### Enable or Disable++```bash+specify workflow overlay disable <workflow-id> <overlay-id>+specify workflow overlay enable <workflow-id> <overlay-id>+```++#### Remove++```bash+specify workflow overlay remove <workflow-id> <overlay-id>+```++Removes the project overlay file.++#### Inspect the Composed Workflow++```bash+specify workflow resolve <workflow-id>+```++Prints the layer stack (base + overlays) and the source attribution for each step after composition. Useful for debugging which overlay contributed or overrode a step.++### Example: Adding Automated Linting after Implementation++Given the built-in `speckit` workflow, create `project-overlay.yml`:++```yaml+id: "add-lint"+extends: "speckit"+priority: 10+edits:+ - insert_after: implement+ step:+ id: run-lint+ type: shell+ run: "ruff check src/"+```++Install it:++```bash+specify workflow overlay add project-overlay.yml --priority 10+```++Run the workflow:++```bash+specify workflow run speckit -i spec="Build a kanban board"+```++The composed workflow will now run the full SDD cycle and execute `ruff check src/` automatically after the `implement` step.++### Example: Replacing a Gate++```yaml+id: "skip-plan-review"+extends: "speckit"+priority: 5+edits:+ - replace: review-plan+ step:+ id: review-plan+ type: command+ command: speckit.plan+ input:+ args: "{{ inputs.spec }}"+```++Lower priority values have higher precedence. Change this overlay to `priority: 5` if it must win a conflict with the `add-lint` overlay above. It replaces the `review-plan` gate with a non-interactive command.++### Interaction with Bundles and Updates++`specify workflow add <local-directory>` installs `workflow.yml` from the local directory into `.specify/workflows/<id>/`.++When an installed workflow is refreshed or reinstalled, project overlays in `.specify/workflows/overlays/<id>/` are preserved because they live outside the installed workflow directory.++### Limitations++- Overlays operate on the step list only. They cannot change workflow metadata (name, description, inputs, `requires`) or expression logic.+- Fan-out templates cannot be used as anchors.+- An overlay that targets a step id that does not exist in the base workflow will raise a validation error when the workflow is resolved.+- Overlays cannot target steps added by other overlays.+- Overlays cannot add new inputs or change the input schema of the base workflow.## Update Workflows```bashdiff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.pyindex fec109bd1..a539c54f4 100644--- a/src/specify_cli/extensions/__init__.py+++ b/src/specify_cli/extensions/__init__.py@@ -136,7 +136,7 @@ def normalize_priority(value: Any, default: int = DEFAULT_HOOK_PRIORITY) -> int:return defaulttry:priority = int(value)- except (TypeError, ValueError):+ except (TypeError, ValueError, OverflowError):return defaultreturn priority if priority >= 1 else defaultdiff --git a/src/specify_cli/workflows/_commands.py b/src/specify_cli/workflows/_commands.pyindex c01903322..88bbbd716 100644--- a/src/specify_cli/workflows/_commands.py+++ b/src/specify_cli/workflows/_commands.py@@ -49,6 +49,13 @@ workflow_step_catalog_app = typer.Typer()workflow_step_app.add_typer(workflow_step_catalog_app, name="catalog")+workflow_overlay_app = typer.Typer(+ name="overlay",+ help="Manage workflow overlays",+ add_completion=False,+)+workflow_app.add_typer(workflow_overlay_app, name="overlay")+def _error_console(json_output: bool):"""Console for error text: stderr under ``--json`` so the JSON stdout@@ -192,6 +199,10 @@ def _reject_unsafe_workflow_storage(project_root: Path) -> None:project_root / ".specify" / "workflows" / "runs",".specify/workflows/runs",)+ _reject_unsafe_dir(+ project_root / ".specify" / "workflows" / "overlays",+ ".specify/workflows/overlays",+ )def _scan_for_workflow_owner(parts: tuple[str, ...]) -> int | None:@@ -366,7 +377,7 @@ def _resolve_installed_workflow_ownership(_WORKFLOW_ID_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")-_RESERVED_WORKFLOW_IDS: frozenset[str] = frozenset({"runs", "steps"})+_RESERVED_WORKFLOW_IDS: frozenset[str] = frozenset({"overlays", "runs", "steps"})def _reject_insecure_download_redirect(old_url: str, new_url: str) -> None:@@ -2386,6 +2397,9 @@ def workflow_info(# Local workflow definition not found on disk; fall back to# catalog/registry lookup below.pass+ except ValueError as exc:+ console.print(f"[red]Error:[/red] Invalid workflow: {_escape_markup(str(exc))}")+ raise typer.Exit(1)if definition:console.print(f"\n[bold cyan]{definition.name}[/bold cyan] ({definition.id})")@@ -3152,6 +3166,102 @@ def workflow_step_catalog_remove(console.print(f"[green]β[/green] Step catalog source '{removed_name}' removed")+@workflow_overlay_app.command("add")+def workflow_overlay_add_cmd(+ source: Path = typer.Argument(..., help="Path to overlay YAML file"),+ priority: int = typer.Option(+ 10,+ "--priority",+ help="Resolution priority (lower = higher precedence, default 10)",+ ),+):+ """Add a project-local overlay for a workflow."""+ from .overlays._commands import workflow_overlay_add++ project_root = _require_specify_project()+ if workflow_overlay_add(project_root, source, priority) is None:+ raise typer.Exit(1)+++@workflow_overlay_app.command("set-priority")+def workflow_overlay_set_priority_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),+ overlay_id: str = typer.Argument(..., help="Overlay ID"),+ priority: int = typer.Argument(+ ..., help="New priority (lower = higher precedence)"+ ),+):+ """Set the priority of a project-local overlay."""+ from .overlays._commands import workflow_overlay_set_priority++ project_root = _require_specify_project()+ if not workflow_overlay_set_priority(project_root, workflow_id, overlay_id, priority):+ raise typer.Exit(1)+++@workflow_overlay_app.command("enable")+def workflow_overlay_enable_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),+ overlay_id: str = typer.Argument(..., help="Overlay ID"),+):+ """Enable a project-local overlay."""+ from .overlays._commands import workflow_overlay_enable++ project_root = _require_specify_project()+ if not workflow_overlay_enable(project_root, workflow_id, overlay_id):+ raise typer.Exit(1)+++@workflow_overlay_app.command("disable")+def workflow_overlay_disable_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),+ overlay_id: str = typer.Argument(..., help="Overlay ID"),+):+ """Disable a project-local overlay."""+ from .overlays._commands import workflow_overlay_disable++ project_root = _require_specify_project()+ if not workflow_overlay_disable(project_root, workflow_id, overlay_id):+ raise typer.Exit(1)+++@workflow_overlay_app.command("remove")+def workflow_overlay_remove_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID the overlay extends"),+ overlay_id: str = typer.Argument(..., help="Overlay ID"),+):+ """Remove a project-local overlay."""+ from .overlays._commands import workflow_overlay_remove++ project_root = _require_specify_project()+ if not workflow_overlay_remove(project_root, workflow_id, overlay_id):+ raise typer.Exit(1)+++@workflow_overlay_app.command("list")+def workflow_overlay_list_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID"),+):+ """List overlays for a workflow."""+ from .overlays._commands import workflow_overlay_list++ project_root = _require_specify_project()+ if workflow_overlay_list(project_root, workflow_id) is None:+ raise typer.Exit(1)+++@workflow_app.command("resolve")+def workflow_resolve_cmd(+ workflow_id: str = typer.Argument(..., help="Workflow ID to resolve"),+):+ """Show layer attribution for a resolved workflow."""+ from .overlays._commands import workflow_resolve++ project_root = _require_specify_project()+ if workflow_resolve(project_root, workflow_id) is None:+ raise typer.Exit(1)++def register(app: typer.Typer) -> None:"""Attach the workflow command group to the root Typer app."""app.add_typer(workflow_app, name="workflow")diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.pyindex 91a9ac2ad..6232fc951 100644--- a/src/specify_cli/workflows/engine.py+++ b/src/specify_cli/workflows/engine.py@@ -79,7 +79,11 @@ class WorkflowDefinition:def from_yaml(cls, path: Path) -> WorkflowDefinition:"""Load a workflow definition from a YAML file."""with open(path, encoding="utf-8") as f:- data = yaml.safe_load(f)+ try:+ data = yaml.safe_load(f)+ except yaml.YAMLError as exc:+ msg = f"Invalid YAML in {path}: {exc}"+ raise ValueError(msg) from excif not isinstance(data, dict):msg = f"Workflow YAML must be a mapping, got {type(data).__name__}."raise ValueError(msg)@@ -88,7 +92,11 @@ class WorkflowDefinition:@classmethoddef from_string(cls, content: str) -> WorkflowDefinition:"""Load a workflow definition from a YAML string."""- data = yaml.safe_load(content)+ try:+ data = yaml.safe_load(content)+ except yaml.YAMLError as exc:+ msg = f"Invalid YAML: {exc}"+ raise ValueError(msg) from excif not isinstance(data, dict):msg = f"Workflow YAML must be a mapping, got {type(data).__name__}."raise ValueError(msg)@@ -727,13 +735,24 @@ class WorkflowEngine:ValueError:If the workflow YAML is invalid."""+ from .overlays import WorkflowResolver+path = Path(source).expanduser()# Try as a direct file path firstif path.suffix.lower() in (".yml", ".yaml") and path.is_file():return WorkflowDefinition.from_yaml(path)- # Try as an installed workflow ID+ # Try as an installed workflow ID, resolving any overlays.+ resolver = WorkflowResolver(self.project_root)+ try:+ return resolver.resolve(str(source))+ except FileNotFoundError:+ # Fall back to the direct workflow.yml path so callers still get+ # the original error when the workflow id is not installed.+ pass++ # Legacy direct path check for workflows installed without registry entries.installed_path = (self.project_root/ ".specify"diff --git a/src/specify_cli/workflows/overlays/__init__.py b/src/specify_cli/workflows/overlays/__init__.pynew file mode 100644index 000000000..2bb87ffbe--- /dev/null+++ b/src/specify_cli/workflows/overlays/__init__.py@@ -0,0 +1,95 @@+"""Workflow overlay resolver β composes installed workflows from layers."""++from __future__ import annotations++from pathlib import Path++from ..engine import WorkflowDefinition+from .composer import StepListComposer+from .layer_sources import (+ BaseWorkflowSource,+ Layer,+ ProjectOverlaySource,+)+from .merge import ComposedStep+from .schema import _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN+++def _validate_workflow_id(workflow_id: str) -> None:+ """Reject workflow IDs that are unsafe as installed-storage path segments."""+ if (+ not isinstance(workflow_id, str)+ or not _SAFE_ID_PATTERN.fullmatch(workflow_id)+ or workflow_id in _RESERVED_WORKFLOW_IDS+ ):+ raise ValueError(f"Invalid workflow ID: {workflow_id!r}")+++class WorkflowResolver:+ """Resolves a workflow ID to its composed ``WorkflowDefinition``.++ Collects layers from two tiers:+ - project-local overlays (``.specify/workflows/overlays/<id>/*.yml``)+ - the base workflow itself (``.specify/workflows/<id>/workflow.yml``)++ Resolution is lower-wins: overlays with lower priority numbers are applied+ later and override earlier edits on the same anchors.+ """++ def __init__(self, project_root: Path) -> None:+ self.project_root = project_root+ self._sources = [+ ProjectOverlaySource(project_root),+ BaseWorkflowSource(project_root),+ ]+ self._composer = StepListComposer()++ def collect_all_layers(+ self, workflow_id: str, *, include_disabled: bool = False+ ) -> list[Layer]:+ """Collect overlays sorted by precedence, followed by the base layer.++ Lower priority numbers win. Ties are sorted alphabetically by source,+ matching ``PresetRegistry.list_by_priority()``. The base workflow is a+ foundation rather than a precedence candidate, so it is kept separate.+ """+ _validate_workflow_id(workflow_id)++ all_layers: list[Layer] = []+ for source in self._sources:+ all_layers.extend(+ source.collect(workflow_id, include_disabled=include_disabled)+ )++ overlays = [layer for layer in all_layers if layer.tier != "base"]+ base_layers = [layer for layer in all_layers if layer.tier == "base"]+ return (+ sorted(overlays, key=lambda layer: (layer.priority, layer.source))+ + base_layers+ )++ def resolve(self, workflow_id: str) -> WorkflowDefinition:+ """Resolve a workflow ID to its composed definition.++ This method composes layers but does not validate workflow semantics;+ callers should validate the returned definition when needed.++ Raises:+ FileNotFoundError: if the workflow cannot be found.+ ValueError: if layer collection/composition fails.+ """+ layers = self.collect_all_layers(workflow_id)+ definition, _ = self._composer.compose(layers)+ if definition is None:+ raise FileNotFoundError(f"Workflow not found: {workflow_id}")+ return definition++ def resolve_with_layers(+ self, workflow_id: str+ ) -> tuple[WorkflowDefinition, list[Layer], list[ComposedStep]]:+ """Resolve a workflow and return its definition plus layer attribution."""+ layers = self.collect_all_layers(workflow_id)+ definition, attribution = self._composer.compose(layers)+ if definition is None:+ raise FileNotFoundError(f"Workflow not found: {workflow_id}")+ return definition, layers, attributiondiff --git a/src/specify_cli/workflows/overlays/_commands.py b/src/specify_cli/workflows/overlays/_commands.pynew file mode 100644index 000000000..cec7d8534--- /dev/null+++ b/src/specify_cli/workflows/overlays/_commands.py@@ -0,0 +1,442 @@+"""CLI handlers for ``specify workflow overlay *`` and ``specify workflow resolve``."""++from __future__ import annotations++from pathlib import Path+from typing import Any++import typer+import yaml++from ..._console import console, err_console+from ...extensions import normalize_priority+from .._commands import (+ _commit_workflow_file,+ _discard_committed_backup_file,+ _reject_unsafe_dir,+ _reject_unsafe_workflow_storage,+ _safe_discard_staged_workflow_file,+ _stage_workflow_file,+)+from . import WorkflowResolver+from .schema import _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN, validate_overlay_yaml+++def _validate_overlay_id_or_exit(id_value: str, label: str) -> None:+ """Validate a single-segment overlay/workflow id from CLI arguments."""+ if not isinstance(id_value, str) or not id_value:+ err_console.print(f"[red]Error:[/red] {label} is required and must be a non-empty string.")+ raise typer.Exit(1)+ if not _SAFE_ID_PATTERN.fullmatch(id_value):+ err_console.print(+ f"[red]Error:[/red] Invalid {label} {id_value!r}: "+ "only lowercase letters, digits, and hyphens are allowed."+ )+ raise typer.Exit(1)+++def _validate_workflow_id_or_exit(workflow_id: str) -> None:+ """Validate a workflow id, treating the overlay root as reserved."""+ _validate_overlay_id_or_exit(workflow_id, "workflow ID")+ if workflow_id in _RESERVED_WORKFLOW_IDS:+ err_console.print(+ f"[red]Error:[/red] Invalid workflow ID {workflow_id!r}: "+ "reserved name."+ )+ raise typer.Exit(1)+++def _overlay_root(project_root: Path) -> Path:+ """Return the project-local overlay root after rejecting unsafe ancestors."""+ _reject_unsafe_workflow_storage(project_root)+ root = project_root / ".specify" / "workflows" / "overlays"+ _reject_unsafe_dir(root, ".specify/workflows/overlays")+ return root+++def _project_overlay_dir(project_root: Path, workflow_id: str) -> Path:+ """Return the project-local overlay directory for a workflow id.++ Raises typer.Exit if the resolved path escapes the overlay root.+ """+ _validate_workflow_id_or_exit(workflow_id)+ root = _overlay_root(project_root)+ target = root / workflow_id+ return _ensure_contained_dir(target, root)+++def _ensure_contained_dir(path: Path, root: Path) -> Path:+ """Ensure *path* resolves inside *root* and is not a symlink.++ Returns *path* if safe. Raises typer.Exit on traversal or symlink.+ """+ _reject_unsafe_dir(root, ".specify/workflows/overlays")+ if path.is_symlink():+ err_console.print(+ f"[red]Error:[/red] Refusing to use symlinked path {path}."+ )+ raise typer.Exit(1)+ if path.exists() and not path.is_dir():+ err_console.print(+ f"[red]Error:[/red] Overlay directory path is not a directory: {path}."+ )+ raise typer.Exit(1)+ try:+ resolved = path.resolve()+ root_resolved = root.resolve()+ resolved.relative_to(root_resolved)+ except ValueError:+ err_console.print(+ f"[red]Error:[/red] Path traversal detected: {path} is outside the allowed directory."+ )+ raise typer.Exit(1)+ return path+++def _find_overlay_file(project_root: Path, workflow_id: str, overlay_id: str) -> Path | None:+ """Locate a project-local overlay file by its manifest ID, not filename.++ Scans all YAML files in the overlay directory and matches on the ``id``+ field inside each manifest. This aligns with ``ProjectOverlaySource.collect()``+ which also derives identity from the manifest, not the filename.+ """+ _validate_workflow_id_or_exit(workflow_id)+ _validate_overlay_id_or_exit(overlay_id, "overlay ID")+ overlay_dir = _project_overlay_dir(project_root, workflow_id)+ if not overlay_dir.is_dir():+ return None+ try:+ entries = sorted(overlay_dir.iterdir())+ except OSError:+ return None+ matches: list[Path] = []+ for path in entries:+ if not path.is_file() or path.suffix not in (".yml", ".yaml"):+ continue+ if path.is_symlink():+ continue+ data, _ = _read_overlay(path)+ if data is None:+ continue+ if data.get("id") == overlay_id:+ matches.append(path)+ if len(matches) > 1:+ paths = ", ".join(str(path) for path in matches)+ err_console.print(+ f"[red]Error:[/red] Duplicate overlay ID '{overlay_id}' in {paths}. "+ "Resolve the duplicate manifest IDs before continuing."+ )+ raise typer.Exit(1)+ return matches[0] if matches else None+++def _ensure_contained_path(path: Path, root: Path) -> Path:+ """Return *path* only if it resolves inside *root*; otherwise raise typer.Exit."""+ _reject_unsafe_dir(root, ".specify/workflows/overlays")+ if path.is_symlink():+ err_console.print(+ f"[red]Error:[/red] Refusing to use symlinked path {path}."+ )+ raise typer.Exit(1)+ try:+ resolved = path.resolve()+ root_resolved = root.resolve()+ resolved.relative_to(root_resolved)+ except ValueError:+ err_console.print(+ f"[red]Error:[/red] Path traversal detected: {path} is outside the allowed directory."+ )+ raise typer.Exit(1)+ return path+++def _read_overlay(path: Path) -> tuple[dict[str, Any] | None, list[str]]:+ """Read and parse an overlay YAML file, returning (data, errors)."""+ try:+ content = path.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError) as exc:+ return None, [f"Failed to read {path}: {exc}"]+ try:+ data = yaml.safe_load(content)+ except yaml.YAMLError as exc:+ return None, [f"Invalid YAML in {path}: {exc}"]+ if not isinstance(data, dict):+ return None, [f"Overlay {path} must be a YAML mapping."]+ return data, []+++def workflow_overlay_add(+ project_root: Path,+ source: Path,+ priority: int | None = None,+) -> Path | None:+ """Add a project-local overlay from a YAML file.++ Returns the path of the installed overlay file, or None on failure.+ """+ _reject_unsafe_workflow_storage(project_root)+ data, errors = _read_overlay(source)+ if data is None:+ for err in errors:+ err_console.print(f"[red]Error:[/red] {err}")+ return None++ # Apply --priority override before validation so a valid CLI priority+ # can fix a missing or invalid priority in the file.+ if priority is not None:+ if isinstance(priority, bool) or not isinstance(priority, int) or priority < 1:+ err_console.print("[red]Error:[/red] Priority must be >= 1.")+ return None+ data["priority"] = normalize_priority(priority)++ overlay, validation_errors = validate_overlay_yaml(data)+ if overlay is None:+ err_console.print("[red]Error:[/red] Overlay validation failed:")+ for err in validation_errors:+ err_console.print(f" \u2022 {err}")+ return None+ data["priority"] = overlay.priority++ target_dir = _project_overlay_dir(project_root, overlay.extends)+ # Reuse an existing .yaml file so we don't create a duplicate .yml layer.+ existing = _find_overlay_file(project_root, overlay.extends, overlay.id)+ if existing is not None:+ target_path = existing+ else:+ target_path = _ensure_contained_path(+ target_dir / f"{overlay.id}.yml", _overlay_root(project_root)+ )++ backup: Path | None = None+ try:+ target_dir.mkdir(parents=True, exist_ok=True)+ existed_before = target_path.exists()+ staged = _stage_workflow_file(target_path.parent)+ try:+ staged.write_bytes(yaml.safe_dump(data, sort_keys=False).encode("utf-8"))+ backup = _commit_workflow_file(staged, target_path, existed_before)+ except BaseException:+ _safe_discard_staged_workflow_file(+ staged, target_path.parent, existed_before+ )+ raise+ except OSError as exc:+ err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")+ return None+ _discard_committed_backup_file(backup)++ console.print(+ f"[green]\u2713[/green] Overlay '{overlay.id}' added for workflow '{overlay.extends}'"+ )+ return target_path+++def _update_overlay_field(+ project_root: Path,+ workflow_id: str,+ overlay_id: str,+ field: str,+ value: Any,+) -> bool:+ """Update a single field in a project-local overlay file."""+ _reject_unsafe_workflow_storage(project_root)+ path = _find_overlay_file(project_root, workflow_id, overlay_id)+ if path is None:+ err_console.print(+ f"[red]Error:[/red] Overlay '{overlay_id}' not found for workflow '{workflow_id}'"+ )+ return False++ data, errors = _read_overlay(path)+ if data is None:+ for err in errors:+ err_console.print(f"[red]Error:[/red] {err}")+ return False++ data[field] = value+ overlay, validation_errors = validate_overlay_yaml(data)+ if overlay is None:+ err_console.print("[red]Error:[/red] Overlay validation failed:")+ for err in validation_errors:+ err_console.print(f" \u2022 {err}")+ return False++ backup: Path | None = None+ try:+ existed_before = path.exists()+ staged = _stage_workflow_file(path.parent)+ try:+ staged.write_bytes(yaml.safe_dump(data, sort_keys=False).encode("utf-8"))+ backup = _commit_workflow_file(staged, path, existed_before)+ except BaseException:+ _safe_discard_staged_workflow_file(staged, path.parent, existed_before)+ raise+ except OSError as exc:+ err_console.print(f"[red]Error:[/red] Failed to write overlay: {exc}")+ return False+ _discard_committed_backup_file(backup)++ return True+++def workflow_overlay_set_priority(+ project_root: Path,+ workflow_id: str,+ overlay_id: str,+ priority: int,+) -> bool:+ """Set the priority of a project-local overlay."""+ if isinstance(priority, bool) or not isinstance(priority, int) or priority < 1:+ err_console.print("[red]Error:[/red] Priority must be >= 1.")+ raise typer.Exit(1)+ normalized_priority = normalize_priority(priority)+ if _update_overlay_field(+ project_root, workflow_id, overlay_id, "priority", normalized_priority+ ):+ console.print(+ f"[green]\u2713[/green] Priority of overlay '{overlay_id}' set to {normalized_priority}"+ )+ return True+ return False+++def workflow_overlay_enable(+ project_root: Path,+ workflow_id: str,+ overlay_id: str,+) -> bool:+ """Enable a project-local overlay."""+ if _update_overlay_field(project_root, workflow_id, overlay_id, "enabled", True):+ console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' enabled")+ return True+ return False+++def workflow_overlay_disable(+ project_root: Path,+ workflow_id: str,+ overlay_id: str,+) -> bool:+ """Disable a project-local overlay."""+ if _update_overlay_field(project_root, workflow_id, overlay_id, "enabled", False):+ console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' disabled")+ return True+ return False+++def workflow_overlay_remove(+ project_root: Path,+ workflow_id: str,+ overlay_id: str,+) -> bool:+ """Remove a project-local overlay file."""+ _reject_unsafe_workflow_storage(project_root)+ path = _find_overlay_file(project_root, workflow_id, overlay_id)+ if path is None:+ err_console.print(+ f"[red]Error:[/red] Overlay '{overlay_id}' not found for workflow '{workflow_id}'"+ )+ return False++ try:+ path.unlink()+ except OSError as exc:+ err_console.print(f"[red]Error:[/red] Failed to remove overlay: {exc}")+ return False++ console.print(f"[green]\u2713[/green] Overlay '{overlay_id}' removed")+ return True+++def workflow_overlay_list(project_root: Path, workflow_id: str) -> list[dict[str, Any]] | None:+ """List all overlays for a workflow and print a summary table.++ Returns the raw list data for machine-readable callers, or None on error.+ """+ _reject_unsafe_workflow_storage(project_root)+ _validate_workflow_id_or_exit(workflow_id)+ resolver = WorkflowResolver(project_root)+ try:+ layers = resolver.collect_all_layers(workflow_id, include_disabled=True)+ except ValueError as exc:+ err_console.print(f"[red]Error:[/red] {exc}")+ return None+ overlays = [layer for layer in layers if layer.tier != "base"]++ if not overlays:+ console.print(f"[yellow]No overlays found for workflow '{workflow_id}'.[/yellow]")+ return []++ console.print(f"Overlays for workflow '{workflow_id}':")+ rows: list[dict[str, Any]] = []+ for layer in overlays:+ overlay = layer.content+ rows.append({+ "id": overlay.id,+ "source": layer.source,+ "tier": layer.tier,+ "priority": normalize_priority(overlay.priority),+ "enabled": overlay.enabled,+ "path": str(layer.path) if layer.path else None,+ })+ enabled_marker = "enabled" if overlay.enabled else "disabled"+ console.print(+ f" \u2022 {overlay.id} (priority={normalize_priority(overlay.priority)}, "+ f"source={layer.source}, {enabled_marker})"+ )+ return rows+++def workflow_resolve(project_root: Path, workflow_id: str) -> dict[str, Any] | None:+ """Print layer attribution for a resolved workflow.++ Returns a serializable attribution payload.+ """+ _reject_unsafe_workflow_storage(project_root)+ _validate_workflow_id_or_exit(workflow_id)+ resolver = WorkflowResolver(project_root)+ try:+ definition, layers, attribution = resolver.resolve_with_layers(workflow_id)+ except FileNotFoundError:+ err_console.print(+ f"[red]Error:[/red] Workflow '{workflow_id}' not found"+ )+ return None+ except ValueError as exc:+ err_console.print(f"[red]Error:[/red] {exc}")+ return None++ console.print(f"Resolved workflow '{workflow_id}':")+ console.print("Layers (highest precedence first):")+ for layer in layers:+ priority = (+ "n/a" if layer.tier == "base" else str(normalize_priority(layer.priority))+ )+ console.print(+ f" \u2022 [{layer.tier}] {layer.source} "+ f"(priority={priority})"+ )++ console.print("Step attribution:")+ for composed in attribution:+ console.print(f" \u2022 {composed.step_id}: {composed.source}")++ return {+ "workflow_id": workflow_id,+ "layers": [+ {+ "source": layer.source,+ "tier": layer.tier,+ "priority": (+ None+ if layer.tier == "base"+ else normalize_priority(layer.priority)+ ),+ }+ for layer in layers+ ],+ "attribution": [+ {"step_id": composed.step_id, "source": composed.source}+ for composed in attribution+ ],+ }diff --git a/src/specify_cli/workflows/overlays/composer.py b/src/specify_cli/workflows/overlays/composer.pynew file mode 100644index 000000000..4a1941727--- /dev/null+++ b/src/specify_cli/workflows/overlays/composer.py@@ -0,0 +1,97 @@+"""Workflow overlay composer β builds a WorkflowDefinition from layers."""++from __future__ import annotations++from typing import Any++from ..engine import WorkflowDefinition+from .layer_sources import Layer+from .merge import OverlayLayer, merge_steps, validate_edits+++class StepListComposer:+ """Compose a workflow from a base layer and overlay layers.++ - The base layer (tier="base") provides the full step list.+ - Overlay layers provide edit operations.+ - Overlays are applied in merge order: highest priority number first,+ lowest last, so lower priority numbers win. Ties are applied by overlay+ ID, with the alphabetically last ID winning.+ - Returns a parsed WorkflowDefinition; callers must validate separately.+ """++ def compose(+ self, layers: list[Layer]+ ) -> tuple[WorkflowDefinition | None, list]:+ """Compose a ``WorkflowDefinition`` from the given layers.++ Returns ``(None, [])`` when no base layer is present.+ """+ base_layer: Layer | None = None+ overlay_layers: list[Layer] = []+ for layer in layers:+ if layer.tier == "base":+ base_layer = layer+ else:+ overlay_layers.append(layer)++ if base_layer is None or base_layer.path is None:+ return None, []++ # Read the base workflow definition from disk.+ base_definition = WorkflowDefinition.from_yaml(base_layer.path)+ base_steps = base_definition.data.get("steps", [])+ if not isinstance(base_steps, list):+ # Preserve the invalid definition intact so validate_workflow can+ # report "'steps' must be a list." to the caller; coercing to []+ # here would mask that error.+ return base_definition, []++ # Last applied wins, so apply lower priority numbers last.+ merge_order = sorted(+ overlay_layers,+ key=lambda layer: (-layer.priority, layer.content.id),+ )++ # Validate edits against base anchors before mutation.+ base_step_ids = self._collect_base_step_ids(base_steps)+ for layer in merge_order:+ edit_errors = validate_edits(layer.content.edits, base_step_ids)+ if edit_errors:+ raise ValueError(+ f"Overlay '{layer.content.id}' has invalid edits:\n - "+ + "\n - ".join(edit_errors)+ )++ composed_steps, attribution = merge_steps(+ base_steps,+ [OverlayLayer(layer.content, layer.source) for layer in merge_order],+ )++ # Build composed data while preserving all non-step fields from base.+ composed_data: dict[str, Any] = dict(base_definition.data)+ composed_data["steps"] = composed_steps++ composed_definition = WorkflowDefinition(composed_data, source_path=base_layer.path)++ return composed_definition, attribution++ def _collect_base_step_ids(self, steps: list[dict[str, Any]]) -> set[str]:+ """Collect all base step IDs reachable in the step tree."""+ ids: set[str] = set()+ for step in steps:+ if not isinstance(step, dict):+ continue+ step_id = step.get("id")+ if isinstance(step_id, str):+ ids.add(step_id)+ for key in ("then", "else", "steps", "default"):+ nested = step.get(key)+ if isinstance(nested, list):+ ids.update(self._collect_base_step_ids(nested))+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ ids.update(self._collect_base_step_ids(case_steps))+ return idsdiff --git a/src/specify_cli/workflows/overlays/layer_sources.py b/src/specify_cli/workflows/overlays/layer_sources.pynew file mode 100644index 000000000..e51aaf70d--- /dev/null+++ b/src/specify_cli/workflows/overlays/layer_sources.py@@ -0,0 +1,234 @@+"""Workflow overlay layer sources."""++from __future__ import annotations++from dataclasses import dataclass+from pathlib import Path++import yaml++from .schema import Overlay, _RESERVED_WORKFLOW_IDS, _SAFE_ID_PATTERN, validate_overlay_yaml+++@dataclass+class Layer:+ """A single layer in the workflow overlay stack."""++ content: Overlay+ source: str+ tier: str+ priority: int+ path: Path | None = None+++class OverlayLoadError(ValueError):+ """Raised when an overlay file cannot be loaded or validated."""++ def __init__(self, path: Path, errors: list[str]) -> None:+ self.path = path+ self.errors = errors+ super().__init__(f"Invalid overlay {path}:\n - " + "\n - ".join(errors))+++def _validate_workflow_id(workflow_id: str, context_path: Path) -> None:+ """Raise OverlayLoadError if workflow_id is not a safe path-segment identifier.++ Mirrors the same check performed by WorkflowResolver so layer sources are+ safe to call directly, without going through the resolver.+ """+ if (+ not isinstance(workflow_id, str)+ or not _SAFE_ID_PATTERN.fullmatch(workflow_id)+ or workflow_id in _RESERVED_WORKFLOW_IDS+ ):+ raise OverlayLoadError(+ context_path,+ [f"Invalid workflow ID: {workflow_id!r}"],+ )+++def _ensure_contained_dir(path: Path, root: Path) -> None:+ """Raise OverlayLoadError if *path* is a symlink, a non-directory, or escapes *root*.++ Mirrors the logic of ``_ensure_contained_dir`` in ``overlays/_commands.py``+ but raises ``OverlayLoadError`` instead of ``typer.Exit`` so layer sources+ can enforce the same invariants without a CLI dependency.++ The caller is responsible for ensuring *root* itself is already validated+ (e.g. via ``_resolve_project_overlay_root``).+ """+ if path.is_symlink():+ raise OverlayLoadError(path, ["Symlinked overlay directories are not allowed"])+ if path.exists() and not path.is_dir():+ raise OverlayLoadError(path, ["Overlay directory path is not a directory"])+ try:+ path.resolve().relative_to(root.resolve())+ except ValueError:+ raise OverlayLoadError(+ path, ["Path traversal detected: directory escapes allowed root"]+ ) from None+++def _resolve_workflows_root(project_root: Path) -> Path:+ """Return the workflow storage root after rejecting unsafe ancestors."""+ project_root_resolved = project_root.resolve()+ workflows_root = project_root / ".specify" / "workflows"++ current = project_root+ for part in (".specify", "workflows"):+ current = current / part+ if current.is_symlink():+ raise OverlayLoadError(+ current,+ [f"Symlinked workflow directories are not allowed ({current})"],+ )+ if current.exists() and not current.is_dir():+ raise OverlayLoadError(+ current,+ [f"Workflow directory path is not a directory ({current})"],+ )++ try:+ workflows_root.resolve().relative_to(project_root_resolved)+ except ValueError:+ raise OverlayLoadError(+ workflows_root,+ ["Workflow directory escapes the project root"],+ ) from None+ return workflows_root+++def _resolve_project_overlay_root(project_root: Path) -> Path:+ """Return the unresolved overlay root after rejecting unsafe ancestors."""+ workflows_root = _resolve_workflows_root(project_root)+ overlays_root = workflows_root / "overlays"+ if overlays_root.is_symlink():+ raise OverlayLoadError(+ overlays_root,+ [f"Symlinked overlay directories are not allowed ({overlays_root})"],+ )+ if overlays_root.exists() and not overlays_root.is_dir():+ raise OverlayLoadError(+ overlays_root,+ [f"Overlay directory path is not a directory ({overlays_root})"],+ )+ return overlays_root+++class ProjectOverlaySource:+ """Project-local overlays: ``.specify/workflows/overlays/<id>/*.yml``."""++ tier = "project-overlay"++ def __init__(self, project_root: Path) -> None:+ self.project_root = project_root+ self.overlays_dir = project_root / ".specify" / "workflows" / "overlays"++ def collect(self, workflow_id: str, *, include_disabled: bool = False) -> list[Layer]:+ """Collect project-local overlays for the given workflow id.++ Args:+ workflow_id: Workflow identifier whose overlay directory to scan.+ include_disabled: When True, return disabled overlays for+ management/list views. Resolution paths keep the default False.+ """+ self.overlays_dir = _resolve_project_overlay_root(self.project_root)+ _validate_workflow_id(workflow_id, self.overlays_dir)+ workflow_overlay_dir = self.overlays_dir / workflow_id+ _ensure_contained_dir(workflow_overlay_dir, self.overlays_dir)+ if not workflow_overlay_dir.is_dir():+ return []+ layers: list[Layer] = []+ overlay_paths_by_id: dict[str, Path] = {}+ try:+ entries = sorted(workflow_overlay_dir.iterdir())+ except OSError as exc:+ raise OverlayLoadError(+ workflow_overlay_dir, [f"Cannot enumerate overlays: {exc}"]+ ) from exc+ for path in entries:+ if not path.is_file() or path.suffix not in (".yml", ".yaml"):+ continue+ if path.is_symlink():+ raise OverlayLoadError(path, ["Symlinked overlay files are not allowed"])+ try:+ data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}+ except yaml.YAMLError as exc:+ raise OverlayLoadError(path, [f"Invalid YAML: {exc}"]) from exc+ except (OSError, UnicodeDecodeError) as exc:+ raise OverlayLoadError(path, [f"Cannot load overlay: {exc}"]) from exc+ if (+ not include_disabled+ and isinstance(data, dict)+ and data.get("enabled", True) is False+ ):+ continue+ overlay, errors = validate_overlay_yaml(data)+ if overlay is None or errors:+ raise OverlayLoadError(path, errors)+ if overlay.extends != workflow_id:+ raise OverlayLoadError(+ path,+ [+ f"Overlay extends {overlay.extends!r}, but is stored under "+ f"workflow {workflow_id!r}."+ ],+ )+ first_path = overlay_paths_by_id.get(overlay.id)+ if first_path is not None:+ raise OverlayLoadError(+ path,+ [+ f"Duplicate overlay id {overlay.id!r}; also declared in "+ f"{first_path}."+ ],+ )+ overlay_paths_by_id[overlay.id] = path+ layers.append(+ Layer(+ content=overlay,+ source=f"project:{overlay.id}",+ tier=self.tier,+ priority=overlay.priority,+ path=path,+ )+ )+ return layers+++class BaseWorkflowSource:+ """Base workflow layer: ``.specify/workflows/<id>/workflow.yml``."""++ tier = "base"++ def __init__(self, project_root: Path) -> None:+ self.project_root = project_root+ self.workflows_dir = project_root / ".specify" / "workflows"++ def collect(self, workflow_id: str, *, include_disabled: bool = False) -> list[Layer]:+ """Return the base workflow as a single layer if it exists."""+ self.workflows_dir = _resolve_workflows_root(self.project_root)+ _validate_workflow_id(workflow_id, self.workflows_dir)+ workflow_dir = self.workflows_dir / workflow_id+ _ensure_contained_dir(workflow_dir, self.workflows_dir)+ path = workflow_dir / "workflow.yml"+ if path.is_symlink():+ raise OverlayLoadError(path, ["Symlinked workflow files are not allowed"])+ if not path.is_file():+ return []+ # The base layer is represented by an Overlay with empty edits.+ overlay = Overlay(+ id=workflow_id,+ extends=workflow_id,+ priority=0,+ edits=[],+ )+ return [+ Layer(+ content=overlay,+ source="base",+ tier=self.tier,+ priority=0,+ path=path,+ )+ ]diff --git a/src/specify_cli/workflows/overlays/merge.py b/src/specify_cli/workflows/overlays/merge.pynew file mode 100644index 000000000..5521b10a7--- /dev/null+++ b/src/specify_cli/workflows/overlays/merge.py@@ -0,0 +1,395 @@+"""Pure-function merge engine for workflow step lists."""++from __future__ import annotations++import copy+from dataclasses import dataclass+from typing import Any++from .schema import VALID_OPERATIONS, Overlay, OverlayEdit+++@dataclass(frozen=True)+class ComposedStep:+ """Attribution tracking for a single composed step."""++ step_id: str+ source: str+++@dataclass(frozen=True)+class OverlayLayer:+ """An overlay together with its layer source for attribution."""++ overlay: Overlay+ source: str+++# Nested step keys that may contain a list of steps.+_NESTED_LIST_KEYS = ("then", "else", "steps", "default")+++def find_step(+ steps: list[dict[str, Any]], step_id: str+) -> tuple[list[dict[str, Any]], int] | None:+ """Recursively locate a step by ID and return its (parent_list, index).++ Searches flat lists and nested lists inside ``then``, ``else``, ``steps``,+ ``default``, and ``cases.*``. Does *not* descend into ``fan-out`` template+ steps because those are runtime-multiplied stamps, not uniquely-addressable+ nodes.+ """+ for i, step in enumerate(steps):+ if not isinstance(step, dict):+ continue+ if step.get("id") == step_id:+ return (steps, i)+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ result = find_step(nested, step_id)+ if result is not None:+ return result+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ result = find_step(case_steps, step_id)+ if result is not None:+ return result+ return None+++def _all_base_step_ids(steps: list[dict[str, Any]]) -> set[str]:+ """Collect all step IDs reachable in a step tree (excluding fan-out templates)."""+ ids: set[str] = set()+ for step in steps:+ if not isinstance(step, dict):+ continue+ step_id = step.get("id")+ if isinstance(step_id, str):+ ids.add(step_id)+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ ids.update(_all_base_step_ids(nested))+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ ids.update(_all_base_step_ids(case_steps))+ return ids+++def _descendant_ids(step: dict[str, Any]) -> set[str]:+ """Return all step IDs nested inside *step* (not including *step* itself)."""+ ids: set[str] = set()+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ ids.update(_all_base_step_ids(nested))+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ ids.update(_all_base_step_ids(case_steps))+ return ids+++def _check_anchor_conflicts(+ anchor_operations: dict[str, str],+ base_steps: list[dict[str, Any]],+) -> list[str]:+ """Return error messages for anchor pairs where one is an ancestor of the other.++ Only flags conflicts where the ancestor's winning edit is ``replace`` or+ ``remove`` β operations that destroy the subtree and make any descendant+ anchor unresolvable. Pure insert operations on an ancestor leave it intact,+ so its descendants remain reachable regardless of processing order.++ Callers should raise on any returned errors before mutating the step tree.+ """+ errors: list[str] = []+ for anchor, operation in sorted(anchor_operations.items()):+ if operation in ("insert_after", "insert_before"):+ # Inserts leave the ancestor step intact; descendants are unaffected.+ continue+ location = find_step(base_steps, anchor)+ if location is None:+ continue # missing anchors are reported by validate_edits+ parent_list, idx = location+ step = parent_list[idx]+ conflicting = set(anchor_operations.keys()) & _descendant_ids(step)+ for child_anchor in sorted(conflicting):+ errors.append(+ f"Anchor conflict: '{anchor}' is an ancestor of '{child_anchor}'. "+ "Targeting both anchors in the same overlay set produces "+ "order-dependent results; restructure edits to avoid nesting."+ )+ return errors+++def _init_sources_recursively(+ steps: list[dict[str, Any]], sources: dict[str, str]+) -> None:+ """Initialize attribution sources for all base steps, recursively."""+ for step in steps:+ if not isinstance(step, dict):+ continue+ step_id = step.get("id")+ if isinstance(step_id, str):+ sources[step_id] = "base"+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ _init_sources_recursively(nested, sources)+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ _init_sources_recursively(case_steps, sources)+++def _record_sources_recursively(+ step: dict[str, Any],+ source: str,+ sources: dict[str, str],+) -> None:+ """Record *source* for a step and all its nested child steps.++ Traverses ``then``, ``else``, ``steps``, ``default``, and ``cases.*``+ so that ``workflow resolve`` attributes every step inside a composite+ insert or replacement to the correct overlay layer.+ """+ step_id = step.get("id")+ if isinstance(step_id, str):+ sources[step_id] = source+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ for child in nested:+ if isinstance(child, dict):+ _record_sources_recursively(child, source, sources)+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ for child in case_steps:+ if isinstance(child, dict):+ _record_sources_recursively(child, source, sources)+++def _remove_sources_recursively(+ step: dict[str, Any],+ sources: dict[str, str],+) -> None:+ """Remove source entries for a step and all its nested child steps.++ Traverses the same nesting keys as ``_record_sources_recursively``.+ """+ step_id = step.get("id")+ if isinstance(step_id, str) and sources.get(step_id) == "base":+ sources.pop(step_id, None)+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ for child in nested:+ if isinstance(child, dict):+ _remove_sources_recursively(child, sources)+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ for child in case_steps:+ if isinstance(child, dict):+ _remove_sources_recursively(child, sources)++++def _build_attribution(+ steps: list[dict[str, Any]],+ sources: dict[str, str],+) -> list[ComposedStep]:+ """Build an ordered attribution list from the composed step tree."""+ result: list[ComposedStep] = []+ for step in steps:+ if not isinstance(step, dict):+ continue+ step_id = step.get("id")+ if isinstance(step_id, str):+ result.append(ComposedStep(step_id, sources.get(step_id, "unknown")))+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ result.extend(_build_attribution(nested, sources))+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_steps in cases.values():+ if isinstance(case_steps, list):+ result.extend(_build_attribution(case_steps, sources))+ return result+++def _traverse_and_apply(+ steps: list[dict[str, Any]],+ edits_by_anchor: dict[str, list[tuple[OverlayLayer, OverlayEdit]]],+ sources: dict[str, str],+) -> list[dict[str, Any]]:+ """Walk the original step tree and apply overlay edits as each step is encountered.++ Edits are always resolved against the *original* structure β this function+ traverses the unmodified list passed in, so a replacement step's new ID can+ never be mistaken for a base anchor. Nested lists (``then``, ``else``, etc.)+ are recursed into only for steps that survive the edit (not for replaced+ steps).++ *edits* are expected to be in merge order (lowest priority first, highest+ priority last); the winning edit for each anchor is ``edits[-1]``.+ """+ result: list[dict[str, Any]] = []++ for step in steps:+ if not isinstance(step, dict):+ result.append(step)+ continue++ step_id = step.get("id")+ edits = edits_by_anchor.get(step_id, []) if isinstance(step_id, str) else []+ winning_edit = edits[-1][1] if edits else None++ if winning_edit is not None and winning_edit.operation == "remove":+ # Winning edit removes this step; ignore all other edits on this anchor.+ # Do NOT call _remove_sources_recursively here: _build_attribution only+ # traverses the result list, so stale sources entries for removed steps+ # are never read. Calling it would incorrectly pop the attribution of a+ # *surviving* step that reuses the same ID (e.g. a replacement step+ # introduced by a higher-priority overlay targeting a different anchor).+ continue++ # Insert before (in merge order).+ for layer, edit in edits:+ if edit.operation == "insert_before":+ new_step = copy.deepcopy(edit.step)+ _record_sources_recursively(new_step, layer.source, sources)+ result.append(new_step)++ if winning_edit is not None and winning_edit.operation == "replace":+ winning_layer = edits[-1][0]+ new_step = copy.deepcopy(winning_edit.step)+ _remove_sources_recursively(step, sources)+ _record_sources_recursively(new_step, winning_layer.source, sources)+ result.append(new_step)+ else:+ # No replacement: keep this step and recurse into its nested lists.+ for key in _NESTED_LIST_KEYS:+ nested = step.get(key)+ if isinstance(nested, list):+ step[key] = _traverse_and_apply(nested, edits_by_anchor, sources)+ cases = step.get("cases")+ if isinstance(cases, dict):+ for case_key, case_steps in cases.items():+ if isinstance(case_steps, list):+ cases[case_key] = _traverse_and_apply(case_steps, edits_by_anchor, sources)+ result.append(step)++ # Insert after (highest priority closest to anchor β reversed merge order).+ for layer, edit in reversed(edits):+ if edit.operation == "insert_after":+ new_step = copy.deepcopy(edit.step)+ _record_sources_recursively(new_step, layer.source, sources)+ result.append(new_step)++ return result+++def merge_steps(+ base_steps: list[dict[str, Any]],+ overlays: list[OverlayLayer],+) -> tuple[list[dict[str, Any]], list[ComposedStep]]:+ """Apply overlays to base steps in merge order and return composed steps.++ *overlays* is expected to be sorted by merge order (lowest priority first,+ highest priority last). The returned step list is a deep copy of the base;+ base_steps is never mutated.++ Higher-wins semantics are enforced for edits that target the same base+ anchor: the highest-priority edit (last in *overlays*) decides the fate of+ the anchor. A lower-priority ``remove`` cannot prevent a higher-priority+ ``replace`` or ``insert_*`` on the same anchor.+ """+ steps = copy.deepcopy(base_steps)+ sources: dict[str, str] = {}+ _init_sources_recursively(steps, sources)++ # Group edits by anchor, preserving merge order.+ edits_by_anchor: dict[str, list[tuple[OverlayLayer, OverlayEdit]]] = {}+ for layer in overlays:+ for edit in layer.overlay.edits:+ edits_by_anchor.setdefault(edit.anchor, []).append((layer, edit))++ # Raise early for non-remove edits that target anchors not present in the base.+ # Overlays always apply to the original tree; they cannot target steps introduced+ # by other overlays.+ base_ids = _all_base_step_ids(base_steps)+ for anchor, anchor_edits in edits_by_anchor.items():+ winning_op = anchor_edits[-1][1].operation+ if winning_op != "remove" and anchor not in base_ids:+ raise ValueError(f"Anchor '{anchor}' not found in workflow steps.")++ # Reject edits that target anchors with a parent/descendant relationship when+ # the ancestor edit replaces or removes its subtree β those produce+ # order-dependent results. Pure insert edits on an ancestor are safe because+ # the ancestor step (and its descendants) remain intact.+ anchor_winning_ops = {+ anchor: anchor_edits[-1][1].operation+ for anchor, anchor_edits in edits_by_anchor.items()+ }+ anchor_conflicts = _check_anchor_conflicts(anchor_winning_ops, base_steps)+ if anchor_conflicts:+ raise ValueError(+ "Overlay anchor conflict(s) detected:\n - " + "\n - ".join(anchor_conflicts)+ )++ # Apply all overlay edits via a single-pass traversal of the original tree.+ # Each edit is resolved against the original step structure, so a replacement+ # step's new ID can never be mistaken for a base anchor in a later edit group.+ result = _traverse_and_apply(steps, edits_by_anchor, sources)++ attribution = _build_attribution(result, sources)+ return result, attribution+++def validate_edits(+ edits: list[OverlayEdit],+ base_step_ids: set[str],+) -> list[str]:+ """Validate overlay edits against a set of known base step IDs.++ Returns a list of human-readable error messages. Does not raise.+ """+ errors: list[str] = []+ for idx, edit in enumerate(edits):+ if edit.operation not in VALID_OPERATIONS:+ errors.append(f"Edit {idx}: invalid operation {edit.operation!r}.")+ continue+ if edit.anchor not in base_step_ids:+ errors.append(+ f"Edit {idx}: anchor '{edit.anchor}' does not match any base step id."+ )+ if edit.operation == "remove":+ if edit.step is not None:+ errors.append(f"Edit {idx}: 'remove' must not include a step.")+ continue+ if not isinstance(edit.step, dict):+ errors.append(f"Edit {idx}: '{edit.operation}' requires a step mapping.")+ continue+ step_id = edit.step.get("id")+ if not isinstance(step_id, str) or not step_id:+ errors.append(f"Edit {idx}: step is missing required 'id'.")+ continue+ if ":" in step_id:+ errors.append(+ f"Edit {idx}: step id {step_id!r} contains ':' which is reserved "+ "for engine-generated nested IDs."+ )+ return errorsdiff --git a/src/specify_cli/workflows/overlays/schema.py b/src/specify_cli/workflows/overlays/schema.pynew file mode 100644index 000000000..221d2fe8e--- /dev/null+++ b/src/specify_cli/workflows/overlays/schema.py@@ -0,0 +1,176 @@+"""Workflow overlay schema β dataclasses and validation for overlay manifests."""++from __future__ import annotations++import re+from dataclasses import dataclass+from typing import Any, Literal++from ...extensions import normalize_priority++# Safe single-segment identifiers: no path separators, no traversal, no dots.+_SAFE_ID_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")+_RESERVED_OVERLAY_WORKFLOW_IDS: frozenset[str] = frozenset({"overlays"})+_RESERVED_WORKFLOW_IDS: frozenset[str] = frozenset({"overlays", "runs", "steps"})++VALID_OPERATIONS = frozenset({"insert_after", "insert_before", "replace", "remove"})++# Map shorthand keys to operation names.+_SHORTHAND_OPERATION_KEYS: frozenset[str] = VALID_OPERATIONS+++@dataclass(frozen=True)+class OverlayEdit:+ """A single edit operation on a workflow step list."""++ operation: Literal["insert_after", "insert_before", "replace", "remove"]+ anchor: str+ step: dict[str, Any] | None = None+++@dataclass+class Overlay:+ """A declared overlay (one YAML file)."""++ id: str+ extends: str+ edits: list[OverlayEdit]+ priority: int = 10+ enabled: bool = True+++def _validate_safe_id(+ value: str,+ field_name: str,+ allow_reserved: bool = False,+ reserved_ids: frozenset[str] = _RESERVED_OVERLAY_WORKFLOW_IDS,+) -> str | None:+ """Return an error message if *value* is not a safe path segment ID."""+ if not isinstance(value, str) or not value:+ return f"Overlay '{field_name}' is required and must be a non-empty string."+ if not _SAFE_ID_PATTERN.fullmatch(value):+ return (+ f"Overlay '{field_name}' {value!r} contains invalid characters; "+ "only lowercase letters, digits, and hyphens are allowed."+ )+ if not allow_reserved and value in reserved_ids:+ return f"Overlay '{field_name}' {value!r} is reserved."+ return None+++def _parse_edit(edit_raw: dict[str, Any], idx: int) -> tuple[OverlayEdit | None, str | None]:+ """Parse a single edit dict into an OverlayEdit or an error string."""+ shorthand_keys = [key for key in _SHORTHAND_OPERATION_KEYS if key in edit_raw]+ has_operation = "operation" in edit_raw++ operation: str | None = None+ anchor: Any = None++ if shorthand_keys and has_operation:+ return None, (+ f"Edit at index {idx} mixes shorthand operation key "+ f"({shorthand_keys[0]!r}) with explicit 'operation' field."+ )++ if len(shorthand_keys) > 1:+ return None, (+ f"Edit at index {idx} has multiple operation keys: "+ f"{', '.join(repr(k) for k in shorthand_keys)}."+ )++ if shorthand_keys:+ operation = shorthand_keys[0]+ anchor = edit_raw[operation]+ elif has_operation:+ operation = edit_raw.get("operation")+ anchor = edit_raw.get("anchor")+ else:+ return None, f"Edit at index {idx} has no operation; expected one of {sorted(VALID_OPERATIONS)}."++ if operation not in VALID_OPERATIONS:+ return None, f"Edit at index {idx} has invalid operation {operation!r}."++ if not isinstance(anchor, str) or not anchor:+ return None, f"Edit at index {idx} has invalid 'anchor'."++ step = edit_raw.get("step")+ if operation == "remove":+ if step is not None:+ return None, f"Edit at index {idx} ('remove') must not include 'step'."+ return OverlayEdit(operation=operation, anchor=anchor), None++ if not isinstance(step, dict):+ return None, f"Edit at index {idx} ('{operation}') requires 'step' mapping."+ step_id = step.get("id")+ if not isinstance(step_id, str) or not step_id:+ return None, f"Edit at index {idx} step is missing required 'id'."+ if ":" in step_id:+ return None, (+ f"Edit at index {idx} step id {step_id!r} contains ':' "+ "which is reserved for engine-generated nested IDs."+ )+ return OverlayEdit(operation=operation, anchor=anchor, step=step), None+++def validate_overlay_yaml(data: dict[str, Any]) -> tuple[Overlay | None, list[str]]:+ """Validate an overlay manifest dict and return (Overlay, errors).++ Errors are returned as a list of strings; validation never raises.+ """+ errors: list[str] = []++ if not isinstance(data, dict):+ return None, ["Overlay manifest must be a mapping."]++ overlay_id = data.get("id")+ if err := _validate_safe_id(overlay_id, "id"):+ errors.append(err)+ overlay_id = ""++ extends = data.get("extends")+ if err := _validate_safe_id(+ extends,+ "extends",+ reserved_ids=_RESERVED_WORKFLOW_IDS,+ ):+ errors.append(err)+ extends = ""++ priority = normalize_priority(data.get("priority", 10))++ edits_raw = data.get("edits")+ edits: list[OverlayEdit] = []+ if not isinstance(edits_raw, list):+ errors.append("Overlay 'edits' is required and must be a list.")+ elif not edits_raw:+ errors.append("Overlay 'edits' must be a non-empty list.")+ else:+ for idx, edit_raw in enumerate(edits_raw):+ if not isinstance(edit_raw, dict):+ errors.append(f"Edit at index {idx} must be a mapping.")+ continue+ edit, err = _parse_edit(edit_raw, idx)+ if err:+ errors.append(err)+ continue+ if edit is not None:+ edits.append(edit)++ enabled = data.get("enabled", True)+ if not isinstance(enabled, bool):+ errors.append("Overlay 'enabled' must be a boolean.")+ enabled = bool(enabled)++ if errors:+ return None, errors++ return (+ Overlay(+ id=overlay_id,+ extends=extends,+ priority=priority,+ edits=edits,+ enabled=enabled,+ ),+ [],+ )diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex b1d984153..8b4cf95dc 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -7091,7 +7091,7 @@ class TestWorkflowRemoveGuard:assert "Invalid workflow ID" in result.outputassert sentinel.read_text(encoding="utf-8") == "keep"- @pytest.mark.parametrize("workflow_id", ["runs", "steps"])+ @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])def test_remove_rejects_reserved_storage_ids(self, project_dir, monkeypatch, workflow_id):@@ -7477,9 +7477,39 @@ steps:# Literal bracketed text survives; Rich did not consume it as a tag.assert "[red]evil[/red]" in out+ def test_add_rejects_reserved_overlay_storage_id(self, temp_dir, monkeypatch):+ """workflow add must not install into the overlay storage directory."""+ from typer.testing import CliRunner+ from specify_cli import app++ (temp_dir / ".specify" / "workflows").mkdir(parents=True)+ overlay_file = temp_dir / "incoming.yml"+ overlay_file.write_text(+ """+schema_version: "1.0"+workflow:+ id: "overlays"+ name: "Bad Workflow"+ version: "1.0.0"+steps:+ - id: step-one+ command: speckit.specify+""".strip()+ + "\n",+ encoding="utf-8",+ )++ monkeypatch.chdir(temp_dir)+ result = CliRunner().invoke(app, ["workflow", "add", str(overlay_file)])++ assert result.exit_code != 0+ assert "Invalid workflow ID" in result.output+ assert not (temp_dir / ".specify" / "workflows" / "overlays" / "workflow.yml").exists()+@pytest.mark.parametrize("workflow_id",[+ "overlays","runs","steps","nested/workflow",diff --git a/tests/workflows/conftest.py b/tests/workflows/conftest.pynew file mode 100644index 000000000..03d28890d--- /dev/null+++ b/tests/workflows/conftest.py@@ -0,0 +1,26 @@+"""Shared fixtures for workflow tests."""++from __future__ import annotations++import shutil+import sys+import tempfile+from pathlib import Path++import pytest+++def temp_dir():+ """Create a temporary directory for tests."""+ tmpdir = tempfile.mkdtemp()+ yield Path(tmpdir)+ shutil.rmtree(tmpdir, ignore_errors=(sys.platform == "win32"))+++def project_dir(temp_dir):+ """Create a mock spec-kit project with ``.specify/workflows/`` directory."""+ workflows_dir = temp_dir / ".specify" / "workflows"+ workflows_dir.mkdir(parents=True, exist_ok=True)+ return temp_dirdiff --git a/tests/workflows/test_overlay_commands.py b/tests/workflows/test_overlay_commands.pynew file mode 100644index 000000000..e06873800--- /dev/null+++ b/tests/workflows/test_overlay_commands.py@@ -0,0 +1,815 @@+"""Tests for workflow overlay CLI commands."""++from __future__ import annotations++from pathlib import Path++import pytest+import typer+import yaml+from typer.testing import CliRunner++from specify_cli import app+++runner = CliRunner()+++def project_dir(tmp_path):+ """Create a mock spec-kit project with ``.specify/workflows/`` directory."""+ workflows_dir = tmp_path / ".specify" / "workflows"+ workflows_dir.mkdir(parents=True, exist_ok=True)+ return tmp_path+++def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:+ wf_dir = project_root / ".specify" / "workflows" / workflow_id+ wf_dir.mkdir(parents=True, exist_ok=True)+ wf_path = wf_dir / "workflow.yml"+ wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return wf_path+++def _write_overlay(project_root: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id+ ov_dir.mkdir(parents=True, exist_ok=True)+ ov_path = ov_dir / f"{overlay_id}.yml"+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return ov_path+++class TestOverlayCli:+ """CLI-level tests for ``specify workflow overlay *``."""++ def test_overlay_add(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]+ )+ assert result.exit_code == 0, result.output+ assert "Overlay 'ov1' added" in result.output++ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ assert installed.is_file()+ data = yaml.safe_load(installed.read_text(encoding="utf-8"))+ assert data["priority"] == 5++ def test_overlay_add_reuses_yaml_extension(self, project_dir, monkeypatch):+ """If <id>.yaml already exists, overlay add must write to it instead of creating <id>.yml."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # Pre-create the overlay using the .yaml extension.+ existing_yaml = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yaml"+ existing_yaml.parent.mkdir(parents=True, exist_ok=True)+ existing_yaml.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 1,+ "edits": [{"remove": "a"}],+ }+ ),+ encoding="utf-8",+ )++ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 20,+ "edits": [{"remove": "a"}],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])+ assert result.exit_code == 0, result.output++ # Should have written to the pre-existing .yaml file.+ assert existing_yaml.is_file()+ data = yaml.safe_load(existing_yaml.read_text(encoding="utf-8"))+ assert data["priority"] == 10++ # Must NOT have created a duplicate .yml alongside the .yaml.+ duplicate_yml = existing_yaml.with_suffix(".yml")+ assert not duplicate_yml.exists(), "duplicate .yml was created alongside existing .yaml"+ assert list(existing_yaml.parent.glob(f".{existing_yaml.name}.*.bak")) == []++ def test_overlay_add_with_priority_override_missing_in_file(self, project_dir, monkeypatch):+ """--priority must fix a missing priority in the overlay file."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # Overlay file has NO priority field+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]+ )+ assert result.exit_code == 0, result.output+ assert "Overlay 'ov1' added" in result.output++ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ assert installed.is_file()+ data = yaml.safe_load(installed.read_text(encoding="utf-8"))+ assert data["priority"] == 5++ def test_overlay_add_defaults_priority_to_ten(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "edits": [{"remove": "a"}],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])++ assert result.exit_code == 0, result.output+ installed = project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ assert yaml.safe_load(installed.read_text(encoding="utf-8"))["priority"] == 10++ def test_overlay_add_rejects_non_positive_priority(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "edits": [{"remove": "a"}],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(+ app,+ ["workflow", "overlay", "add", str(overlay_file), "--priority", "0"],+ )++ assert result.exit_code == 1+ assert "must be >= 1" in result.output++ def test_overlay_set_priority(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "set-priority", "wf", "ov1", "20"]+ )+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ ).read_text(encoding="utf-8")+ )+ assert data["priority"] == 20+ assert list(+ (project_dir / ".specify" / "workflows" / "overlays" / "wf").glob(+ ".ov1.yml.*.bak"+ )+ ) == []++ def test_overlay_set_priority_rejects_zero(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)++ result = runner.invoke(+ app, ["workflow", "overlay", "set-priority", "wf", "ov1", "0"]+ )++ assert result.exit_code == 1+ assert "must be >= 1" in result.output++ def test_overlay_set_priority_rejects_ids_with_trailing_newline(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "set-priority", "wf", "ov1\n", "20"]+ )+ assert result.exit_code == 1+ assert "Invalid overlay ID" in result.output++ result = runner.invoke(+ app, ["workflow", "overlay", "set-priority", "wf\n", "ov1", "20"]+ )+ assert result.exit_code == 1+ assert "Invalid workflow ID" in result.output++ def test_overlay_disable_and_enable(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "ov1"])+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ ).read_text(encoding="utf-8")+ )+ assert data["enabled"] is False++ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "ov1"])+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ ).read_text(encoding="utf-8")+ )+ assert data["enabled"] is True++ def test_overlay_remove(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "ov1"])+ assert result.exit_code == 0, result.output+ assert not (+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "ov1.yml"+ ).exists()++ def test_overlay_list(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])+ assert result.exit_code == 0, result.output+ assert "ov1" in result.output++ def test_overlay_list_shows_disabled_overlay(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "enabled": False,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])+ assert result.exit_code == 0, result.output+ assert "ov1" in result.output+ assert "disabled" in result.output++ def test_workflow_resolve(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "resolve", "wf"])+ assert result.exit_code == 0, result.output+ assert "base" in result.output+ assert "project:ov1" in result.output+ assert "new" in result.output+ assert "priority=n/a" in result.output++ from specify_cli.workflows.overlays._commands import workflow_resolve++ payload = workflow_resolve(project_dir, "wf")+ assert payload is not None+ assert payload["layers"][-1]["tier"] == "base"+ assert payload["layers"][-1]["priority"] is None++ def test_workflow_resolve_equal_priority_layers_sort_by_source(self, project_dir, monkeypatch):+ """Equal-priority overlays are listed alphabetically by source."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # "zzz" sorts last alphabetically, so the composer applies it last and wins.+ # Resolver layer output follows the common priority/source sort order.+ _write_overlay(+ project_dir,+ "wf",+ "aaa",+ {+ "id": "aaa",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "aaa-step", "type": "command", "command": "echo"},+ }+ ],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "zzz",+ {+ "id": "zzz",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "zzz-step", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ result = runner.invoke(app, ["workflow", "resolve", "wf"])+ assert result.exit_code == 0, result.output+ zzz_pos = result.output.index("project:zzz")+ aaa_pos = result.output.index("project:aaa")+ assert aaa_pos < zzz_pos++ def test_workflow_add_does_not_copy_overlays(self, project_dir, monkeypatch, tmp_path):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ source_dir = tmp_path / "source-wf"+ source_dir.mkdir()+ (source_dir / "workflow.yml").write_text(+ yaml.safe_dump(+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ }+ ),+ encoding="utf-8",+ )+ overlays_dir = source_dir / "overlays"+ overlays_dir.mkdir()+ (overlays_dir / "ov1.yml").write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(app, ["workflow", "add", str(source_dir)])+ assert result.exit_code == 0, result.output+ # Overlays in the source directory should NOT be copied β workflow add+ # only installs the workflow.yml, not sibling overlays.+ installed_overlay = (+ project_dir / ".specify" / "workflows" / "wf" / "overlays" / "ov1.yml"+ )+ assert not installed_overlay.exists()+++class TestOverlayFilenameVsManifestId:+ """Overlay identity must come from the manifest ``id`` field, not the filename.++ This matches the project-wide convention: presets use ``preset.id``,+ extensions use ``extension.id``, workflows use ``workflow.id``, and+ workflow steps use ``step.type_key``. Overlays must follow the same pattern.+ """++ def _write_mismatched_overlay(+ self, project_root: Path, workflow_id: str, filename: str, manifest_id: str, data: dict+ ) -> Path:+ """Write an overlay file where filename != manifest id."""+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id+ ov_dir.mkdir(parents=True, exist_ok=True)+ ov_path = ov_dir / filename+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return ov_path++ def test_find_overlay_by_manifest_id_not_filename(self, project_dir, monkeypatch):+ """_find_overlay_file must locate overlays by manifest id, not filename."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # File is named "custom.yml" but manifest declares id: "lint"+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "custom.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ },+ )++ from specify_cli.workflows.overlays._commands import _find_overlay_file++ # Must find by manifest id "lint", not by filename "custom"+ found = _find_overlay_file(project_dir, "wf", "lint")+ assert found is not None+ assert found.name == "custom.yml"++ # Must NOT find by filename stem "custom"+ not_found = _find_overlay_file(project_dir, "wf", "custom")+ assert not_found is None++ def test_enable_disable_with_mismatched_filename(self, project_dir, monkeypatch):+ """enable/disable must work when filename != manifest id."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "custom.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "disable", "wf", "lint"])+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(+ encoding="utf-8"+ )+ )+ assert data["enabled"] is False++ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "lint"])+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(+ encoding="utf-8"+ )+ )+ assert data["enabled"] is True++ def test_set_priority_with_mismatched_filename(self, project_dir, monkeypatch):+ """set-priority must work when filename != manifest id."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "custom.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "set-priority", "wf", "lint", "25"])+ assert result.exit_code == 0, result.output+ data = yaml.safe_load(+ (project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml").read_text(+ encoding="utf-8"+ )+ )+ assert data["priority"] == 25++ def test_remove_with_mismatched_filename(self, project_dir, monkeypatch):+ """remove must work when filename != manifest id."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "custom.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ },+ )++ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "lint"])+ assert result.exit_code == 0, result.output+ assert not (+ project_dir / ".specify" / "workflows" / "overlays" / "wf" / "custom.yml"+ ).exists()++ def test_duplicate_manifest_id_is_rejected(self, project_dir, monkeypatch):+ """Two files with the same manifest ID are ambiguous."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # Two files, both declare id: "lint"+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "aaa.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ },+ )+ self._write_mismatched_overlay(+ project_dir,+ "wf",+ "zzz.yml",+ "lint",+ {+ "id": "lint",+ "extends": "wf",+ "priority": 20,+ "edits": [{"remove": "a"}],+ },+ )++ from specify_cli.workflows.overlays._commands import _find_overlay_file++ with pytest.raises(typer.Exit):+ _find_overlay_file(project_dir, "wf", "lint")diff --git a/tests/workflows/test_overlay_composer.py b/tests/workflows/test_overlay_composer.pynew file mode 100644index 000000000..1092be921--- /dev/null+++ b/tests/workflows/test_overlay_composer.py@@ -0,0 +1,153 @@+"""Tests for StepListComposer validation and error handling."""++from __future__ import annotations++from pathlib import Path++import pytest+import yaml++from specify_cli.workflows.overlays import WorkflowResolver+from specify_cli.workflows.overlays.composer import StepListComposer+from specify_cli.workflows.overlays.layer_sources import BaseWorkflowSource, Layer+from specify_cli.workflows.overlays.schema import Overlay, OverlayEdit+++def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:+ wf_dir = project_root / ".specify" / "workflows" / workflow_id+ wf_dir.mkdir(parents=True, exist_ok=True)+ wf_path = wf_dir / "workflow.yml"+ wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return wf_path+++class TestStepListComposerValidation:+ """Composer validates edits before applying them."""++ def test_composer_reports_invalid_anchors(self, project_dir):+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ base_layer = BaseWorkflowSource(project_dir).collect("wf")[0]++ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "missing", {"id": "new", "type": "command", "command": "echo"})],+ )+ layer = Layer(content=overlay, source="project:ov", tier="project-overlay", priority=10)+ composer = StepListComposer()+ with pytest.raises(ValueError, match="does not match any base step id"):+ composer.compose([base_layer, layer])++ def test_composer_validates_edits_before_merge(self, project_dir):+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "a", {"id": "bad:id", "type": "command", "command": "echo"})],+ )+ layer = Layer(content=overlay, source="project:ov", tier="project-overlay", priority=10)+ composer = StepListComposer()+ with pytest.raises(ValueError, match="bad:id"):+ composer.compose([BaseWorkflowSource(project_dir).collect("wf")[0], layer])++ def test_resolver_reports_invalid_anchor_as_validation_error(self, project_dir):+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "missing",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )+ # Manually inject the overlay by writing it to disk in the correct location.+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ overlay_dir.mkdir(parents=True, exist_ok=True)+ (overlay_dir / "ov.yml").write_text(overlay_file.read_text(encoding="utf-8"), encoding="utf-8")++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError, match="missing"):+ resolver.resolve("wf")++ def test_composer_applies_lower_priority_last(self, project_dir):+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "base"}],+ },+ )+ high_number = Overlay(+ id="high-number",+ extends="wf",+ priority=20,+ edits=[+ OverlayEdit(+ "replace",+ "a",+ {"id": "a", "type": "command", "command": "priority-20"},+ )+ ],+ )+ low_number = Overlay(+ id="low-number",+ extends="wf",+ priority=5,+ edits=[+ OverlayEdit(+ "replace",+ "a",+ {"id": "a", "type": "command", "command": "priority-5"},+ )+ ],+ )++ definition, attribution = StepListComposer().compose(+ [+ BaseWorkflowSource(project_dir).collect("wf")[0],+ Layer(high_number, "project:high-number", "project-overlay", 20),+ Layer(low_number, "project:low-number", "project-overlay", 5),+ ]+ )++ assert definition is not None+ assert definition.data["steps"][0]["command"] == "priority-5"+ assert attribution[0].source == "project:low-number"diff --git a/tests/workflows/test_overlay_layer_sources.py b/tests/workflows/test_overlay_layer_sources.pynew file mode 100644index 000000000..fc6e30ef3--- /dev/null+++ b/tests/workflows/test_overlay_layer_sources.py@@ -0,0 +1,272 @@+"""Tests for ProjectOverlaySource and BaseWorkflowSource."""++from __future__ import annotations++from pathlib import Path+from unittest.mock import patch++import pytest+import yaml++from specify_cli.workflows.overlays.layer_sources import (+ BaseWorkflowSource,+ OverlayLoadError,+ ProjectOverlaySource,+)+++def project_dir(tmp_path: Path) -> Path:+ workflows_dir = tmp_path / ".specify" / "workflows"+ workflows_dir.mkdir(parents=True, exist_ok=True)+ return tmp_path+++def _write_overlay_file(project_dir: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:+ ov_dir = project_dir / ".specify" / "workflows" / "overlays" / workflow_id+ ov_dir.mkdir(parents=True, exist_ok=True)+ path = ov_dir / f"{overlay_id}.yml"+ path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return path+++class TestProjectOverlaySourceFileReadErrors:+ """File-read errors must be wrapped in OverlayLoadError, not leaked as raw tracebacks."""++ def test_oserror_raises_overlay_load_error(self, project_dir: Path) -> None:+ """An OSError from read_text (e.g. permission denied) is wrapped in OverlayLoadError."""+ _write_overlay_file(+ project_dir,+ "wf",+ "ov1",+ {"id": "ov1", "extends": "wf", "priority": 5, "edits": []},+ )+ source = ProjectOverlaySource(project_dir)+ with patch.object(Path, "read_text", side_effect=OSError("Permission denied")):+ with pytest.raises(OverlayLoadError) as exc_info:+ source.collect("wf")+ assert exc_info.value.errors, "OverlayLoadError must carry a non-empty errors list"++ def test_unicode_error_raises_overlay_load_error(self, project_dir: Path) -> None:+ """A file containing non-UTF-8 bytes raises OverlayLoadError, not UnicodeDecodeError."""+ ov_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ ov_dir.mkdir(parents=True, exist_ok=True)+ # Write raw invalid UTF-8 bytes directly so read_text(encoding="utf-8") fails.+ bad_file = ov_dir / "bad.yml"+ bad_file.write_bytes(b"\xff\xfe invalid utf-8")++ source = ProjectOverlaySource(project_dir)+ with pytest.raises(OverlayLoadError) as exc_info:+ source.collect("wf")+ assert exc_info.value.errors, "OverlayLoadError must carry a non-empty errors list"+++_UNSAFE_IDS = [+ "../outside",+ "../../escape",+ "nested/workflow",+ "wf\n",+ "overlays",+ "runs",+ "steps",+ "",+ "/absolute",+ "UPPER",+ "has space",+]+++class TestProjectOverlaySourceIdValidation:+ """ProjectOverlaySource.collect() must reject unsafe IDs before path construction."""++ @pytest.mark.parametrize("workflow_id", _UNSAFE_IDS)+ def test_rejects_unsafe_id(self, project_dir: Path, workflow_id: str) -> None:+ source = ProjectOverlaySource(project_dir)+ with pytest.raises(OverlayLoadError, match="Invalid workflow ID"):+ source.collect(workflow_id)++ @pytest.mark.parametrize("workflow_id", _UNSAFE_IDS)+ def test_does_not_access_filesystem_for_unsafe_id(+ self, project_dir: Path, workflow_id: str+ ) -> None:+ """No directory walk or file read should happen for an invalid ID."""+ source = ProjectOverlaySource(project_dir)+ with patch.object(Path, "iterdir", side_effect=AssertionError("iterdir called")):+ with pytest.raises(OverlayLoadError, match="Invalid workflow ID"):+ source.collect(workflow_id)+++class TestProjectOverlaySourceContainment:+ """ProjectOverlaySource.collect() must enforce containment of the workflow overlay dir."""++ def test_rejects_symlinked_workflow_overlay_dir(self, project_dir: Path, tmp_path: Path) -> None:+ """A symlinked per-workflow overlay directory must be rejected."""+ real_dir = tmp_path / "real-overlay"+ real_dir.mkdir()+ overlay_root = project_dir / ".specify" / "workflows" / "overlays"+ overlay_root.mkdir(parents=True, exist_ok=True)+ link = overlay_root / "wf"+ link.symlink_to(real_dir)++ source = ProjectOverlaySource(project_dir)+ with pytest.raises(OverlayLoadError, match="Symlinked overlay directories are not allowed"):+ source.collect("wf")++ def test_rejects_workflow_overlay_dir_escaping_root(+ self, project_dir: Path, tmp_path: Path+ ) -> None:+ """A workflow overlay dir that resolves outside the overlay root must be rejected.++ This requires the ID itself to pass validation but the resolved path to escape β+ which is possible if the overlay root itself is a junction/mount that resolves+ outside the project root; or in edge cases on case-insensitive file systems.+ We simulate it by patching Path.resolve to return an outside path.+ """+ overlay_root = project_dir / ".specify" / "workflows" / "overlays"+ overlay_root.mkdir(parents=True, exist_ok=True)+ workflow_overlay_dir = overlay_root / "wf"+ workflow_overlay_dir.mkdir()++ outside = tmp_path / "outside" / "wf"+ outside.mkdir(parents=True)++ original_resolve = Path.resolve++ def fake_resolve(self: Path, **kwargs: object) -> Path:+ if self == workflow_overlay_dir:+ return outside+ return original_resolve(self, **kwargs)++ source = ProjectOverlaySource(project_dir)+ with patch.object(Path, "resolve", fake_resolve):+ with pytest.raises(OverlayLoadError, match="Path traversal detected"):+ source.collect("wf")+++class TestProjectOverlaySourceDisabledFiltering:+ """ProjectOverlaySource.collect() should expose disabled entries only on opt-in."""++ def test_skips_disabled_by_default(self, project_dir: Path) -> None:+ _write_overlay_file(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 5,+ "enabled": False,+ "edits": [{"remove": "a"}],+ },+ )++ source = ProjectOverlaySource(project_dir)+ assert source.collect("wf") == []++ def test_can_include_disabled_for_management_views(self, project_dir: Path) -> None:+ _write_overlay_file(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 5,+ "enabled": False,+ "edits": [{"remove": "a"}],+ },+ )++ source = ProjectOverlaySource(project_dir)+ layers = source.collect("wf", include_disabled=True)+ assert [layer.content.id for layer in layers] == ["ov1"]+ assert layers[0].content.enabled is False++ def test_skips_invalid_disabled_overlay_during_resolution(self, project_dir: Path) -> None:+ _write_overlay_file(+ project_dir,+ "wf",+ "disabled",+ {+ "id": "disabled",+ "extends": "wf",+ "enabled": False,+ "edits": "not-a-list",+ },+ )++ source = ProjectOverlaySource(project_dir)+ assert source.collect("wf") == []+ with pytest.raises(OverlayLoadError, match="edits"):+ source.collect("wf", include_disabled=True)++ def test_rejects_duplicate_manifest_ids(self, project_dir: Path) -> None:+ data = {+ "id": "duplicate",+ "extends": "wf",+ "edits": [{"remove": "a"}],+ }+ _write_overlay_file(project_dir, "wf", "first", data)+ _write_overlay_file(project_dir, "wf", "second", data)++ with pytest.raises(OverlayLoadError, match="Duplicate overlay id"):+ ProjectOverlaySource(project_dir).collect("wf")+++class TestBaseWorkflowSourceIdValidation:+ """BaseWorkflowSource.collect() must reject unsafe IDs before path construction."""++ @pytest.mark.parametrize("workflow_id", _UNSAFE_IDS)+ def test_rejects_unsafe_id(self, project_dir: Path, workflow_id: str) -> None:+ source = BaseWorkflowSource(project_dir)+ with pytest.raises(OverlayLoadError, match="Invalid workflow ID"):+ source.collect(workflow_id)+++class TestBaseWorkflowSourceContainment:+ """BaseWorkflowSource.collect() must enforce the same checks as _safe_workflow_id_dir."""++ def test_rejects_symlinked_workflow_dir(self, project_dir: Path, tmp_path: Path) -> None:+ """A symlinked workflow directory must be rejected."""+ real_dir = tmp_path / "real-wf"+ real_dir.mkdir()+ (real_dir / "workflow.yml").write_text("schema_version: '1.0'\n", encoding="utf-8")++ workflows_dir = project_dir / ".specify" / "workflows"+ workflows_dir.mkdir(parents=True, exist_ok=True)+ link = workflows_dir / "wf"+ link.symlink_to(real_dir)++ source = BaseWorkflowSource(project_dir)+ with pytest.raises(OverlayLoadError, match="Symlinked overlay directories are not allowed"):+ source.collect("wf")++ def test_rejects_symlinked_workflow_yml(self, project_dir: Path, tmp_path: Path) -> None:+ """A symlinked workflow.yml must be rejected even if the directory is real."""+ real_yml = tmp_path / "workflow.yml"+ real_yml.write_text("schema_version: '1.0'\n", encoding="utf-8")++ workflows_dir = project_dir / ".specify" / "workflows"+ wf_dir = workflows_dir / "wf"+ wf_dir.mkdir(parents=True, exist_ok=True)+ link = wf_dir / "workflow.yml"+ link.symlink_to(real_yml)++ source = BaseWorkflowSource(project_dir)+ with pytest.raises(OverlayLoadError, match="Symlinked workflow files are not allowed"):+ source.collect("wf")++ def test_missing_workflow_returns_empty(self, project_dir: Path) -> None:+ """A workflow directory that does not exist returns an empty layer list."""+ source = BaseWorkflowSource(project_dir)+ assert source.collect("no-such-wf") == []++ def test_rejects_symlinked_workflows_root(self, project_dir: Path, tmp_path: Path) -> None:+ outside = tmp_path / "outside"+ outside.mkdir()+ workflows_dir = project_dir / ".specify" / "workflows"+ workflows_dir.rmdir()+ workflows_dir.symlink_to(outside)++ with pytest.raises(OverlayLoadError, match="Symlinked workflow directories"):+ BaseWorkflowSource(project_dir).collect("wf")diff --git a/tests/workflows/test_overlay_merge.py b/tests/workflows/test_overlay_merge.pynew file mode 100644index 000000000..17790d680--- /dev/null+++ b/tests/workflows/test_overlay_merge.py@@ -0,0 +1,718 @@+"""Tests for the workflow overlay merge engine."""++from __future__ import annotations++import copy+from typing import Any++import pytest++from specify_cli.workflows.overlays.merge import (+ ComposedStep,+ OverlayLayer,+ find_step,+ merge_steps,+ validate_edits,+)+from specify_cli.workflows.overlays.schema import Overlay, OverlayEdit+++def _step(id: str, **kwargs: Any) -> dict[str, Any]: # noqa: A002+ """Build a minimal step dict with the given id."""+ return {"id": id, "type": "command", "command": "speckit.specify", **kwargs}+++def _layer(overlay: Overlay, source: str) -> OverlayLayer:+ """Build an OverlayLayer for merge_steps."""+ return OverlayLayer(overlay, source)+++class TestFindStep:+ """Recursive anchor lookup across nested step lists."""++ def test_find_step_flat(self):+ steps = [_step("a"), _step("b"), _step("c")]+ result = find_step(steps, "b")+ assert result is not None+ assert result[0] is steps+ assert result[1] == 1++ def test_find_step_missing(self):+ steps = [_step("a"), _step("b")]+ assert find_step(steps, "missing") is None++ def test_find_step_in_then(self):+ steps = [+ {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("then-a")],+ "else": [_step("else-b")],+ },+ ]+ result = find_step(steps, "then-a")+ assert result is not None+ assert result[0] is steps[0]["then"]+ assert result[1] == 0++ def test_find_step_in_else(self):+ steps = [+ {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("then-a")],+ "else": [_step("else-b")],+ },+ ]+ result = find_step(steps, "else-b")+ assert result is not None+ assert result[0] is steps[0]["else"]+ assert result[1] == 0++ def test_find_step_in_nested_steps(self):+ steps = [+ {+ "id": "while-1",+ "type": "while",+ "condition": "true",+ "steps": [_step("inner-a"), _step("inner-b")],+ },+ ]+ result = find_step(steps, "inner-b")+ assert result is not None+ assert result[0] is steps[0]["steps"]+ assert result[1] == 1++ def test_find_step_in_switch_cases(self):+ steps = [+ {+ "id": "switch-1",+ "type": "switch",+ "expression": "{{ inputs.x }}",+ "cases": {+ "one": [_step("case-a")],+ "two": [_step("case-b")],+ },+ "default": [_step("default-c")],+ },+ ]+ assert find_step(steps, "case-b")[1] == 0+ assert find_step(steps, "default-c")[1] == 0++ def test_find_step_not_in_fan_out_template(self):+ steps = [+ {+ "id": "fan-1",+ "type": "fan-out",+ "items": "{{ inputs.items }}",+ "step": {"id": "template-x", "type": "command", "command": "echo"},+ },+ ]+ assert find_step(steps, "template-x") is None+++class TestMergeSteps:+ """Composition of multiple overlays in merge order."""++ def test_merge_steps_no_overlays(self):+ base = [_step("a"), _step("b")]+ steps, attribution = merge_steps(base, [])+ assert [s["id"] for s in steps] == ["a", "b"]+ assert attribution == [ComposedStep("a", "base"), ComposedStep("b", "base")]++ def test_merge_steps_single_overlay(self):+ base = [_step("a"), _step("b")]+ overlay = Overlay(+ id="ov1",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "a", _step("new"))],+ )+ steps, attribution = merge_steps(base, [_layer(overlay, "project:ov1")])+ assert [s["id"] for s in steps] == ["a", "new", "b"]+ assert attribution == [+ ComposedStep("a", "base"),+ ComposedStep("new", "project:ov1"),+ ComposedStep("b", "base"),+ ]++ def test_merge_steps_higher_priority_wins(self):+ base = [_step("a")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("insert_after", "a", _step("low-step"))],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "a", _step("high-step"))],+ )+ steps, attribution = merge_steps(base, [_layer(low, "project:low"), _layer(high, "project:high")])+ # low applied first, then high; both insert after 'a', so high-step ends+ # closer to the anchor (higher priority wins the conflict).+ assert [s["id"] for s in steps] == ["a", "high-step", "low-step"]+ assert attribution == [+ ComposedStep("a", "base"),+ ComposedStep("high-step", "project:high"),+ ComposedStep("low-step", "project:low"),+ ]++ def test_merge_steps_replace_wins_over_insert(self):+ """Overlays apply to the original tree only; targeting an overlay-introduced step raises."""+ base = [_step("a")]+ insert = Overlay(+ id="insert",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("insert_after", "a", _step("inserted"))],+ )+ replace = Overlay(+ id="replace",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "inserted", _step("replaced"))],+ )+ # "inserted" is not a base step β overlays cannot target each other's steps.+ with pytest.raises(ValueError, match="Anchor 'inserted' not found"):+ merge_steps(base, [_layer(insert, "project:insert"), _layer(replace, "project:replace")])++ def test_merge_steps_does_not_mutate_base(self):+ base = [_step("a")]+ overlay = Overlay(+ id="ov1",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "a", _step("new"))],+ )+ original = copy.deepcopy(base)+ merge_steps(base, [_layer(overlay, "project:ov1")])+ assert base == original++ def test_merge_steps_attribution_uses_source_not_overlay_id(self):+ base = [_step("a")]+ overlay = Overlay(+ id="same-id",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "a", _step("new"))],+ )+ steps, attribution = merge_steps(base, [_layer(overlay, "installed:same-id")])+ assert [s["id"] for s in steps] == ["a", "new"]+ assert attribution == [+ ComposedStep("a", "base"),+ ComposedStep("new", "installed:same-id"),+ ]++ def test_merge_steps_nested_base_attribution(self):+ base = [+ {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("then-a")],+ "else": [_step("else-b")],+ },+ ]+ steps, attribution = merge_steps(base, [])+ assert attribution == [+ ComposedStep("if-1", "base"),+ ComposedStep("then-a", "base"),+ ComposedStep("else-b", "base"),+ ]++ def test_merge_steps_higher_replace_wins_lower_replace_same_anchor(self):+ base = [_step("implement")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("replace", "implement", _step("low-implement"))],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "implement", _step("high-implement"))],+ )+ steps, attribution = merge_steps(base, [_layer(low, "project:low"), _layer(high, "project:high")])+ assert [s["id"] for s in steps] == ["high-implement"]+ assert any(+ composed.step_id == "high-implement" and composed.source == "project:high"+ for composed in attribution+ )++ def test_merge_steps_higher_replace_wins_after_lower_remove_same_anchor(self):+ base = [_step("implement")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("remove", "implement")],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "implement", _step("high-implement"))],+ )+ steps, attribution = merge_steps(base, [_layer(low, "project:low"), _layer(high, "project:high")])+ assert [s["id"] for s in steps] == ["high-implement"]++ def test_merge_steps_higher_insert_wins_after_lower_remove_same_anchor(self):+ base = [_step("implement")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("remove", "implement")],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", "implement", _step("high-after"))],+ )+ steps, attribution = merge_steps(base, [_layer(low, "project:low"), _layer(high, "project:high")])+ assert [s["id"] for s in steps] == ["implement", "high-after"]+ assert attribution == [+ ComposedStep("implement", "base"),+ ComposedStep("high-after", "project:high"),+ ]++ def test_merge_steps_later_overlay_wins_tie_same_anchor(self):+ """When two overlays have the same priority, the one applied later wins."""+ base = [_step("a")]+ first = Overlay(+ id="first",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "a", _step("first-replace"))],+ )+ second = Overlay(+ id="second",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "a", _step("second-replace"))],+ )+ # Merge order: first applied, then second wins tie.+ steps, attribution = merge_steps(+ base,+ [+ _layer(first, "overlay:first"),+ _layer(second, "overlay:second"),+ ],+ )+ assert [s["id"] for s in steps] == ["second-replace"]+ assert any(+ composed.step_id == "second-replace" and composed.source == "overlay:second"+ for composed in attribution+ )++ def test_merge_steps_insert_after_then_replace_same_anchor_id_change(self):+ """Inserts must be applied before the winning replace so the anchor still exists.++ Regression: when a replace changes the step ID, applying it before inserts+ causes ``find_step`` to fail on the now-gone original anchor.+ """+ base = [_step("build")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("insert_after", "build", _step("test"))],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "build", _step("compile"))],+ )+ steps, attribution = merge_steps(+ base, [_layer(low, "project:low"), _layer(high, "project:high")]+ )+ # The insert should land after the original anchor position, then the+ # anchor is replaced. Final order: ["compile", "test"].+ assert [s["id"] for s in steps] == ["compile", "test"]+ assert attribution == [+ ComposedStep("compile", "project:high"),+ ComposedStep("test", "project:low"),+ ]++ def test_merge_steps_insert_before_then_replace_same_anchor_id_change(self):+ """Same as above but with insert_before β anchor must still be findable."""+ base = [_step("build")]+ low = Overlay(+ id="low",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("insert_before", "build", _step("lint"))],+ )+ high = Overlay(+ id="high",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "build", _step("compile"))],+ )+ steps, attribution = merge_steps(+ base, [_layer(low, "project:low"), _layer(high, "project:high")]+ )+ assert [s["id"] for s in steps] == ["lint", "compile"]+ assert attribution == [+ ComposedStep("lint", "project:low"),+ ComposedStep("compile", "project:high"),+ ]++ def test_merge_steps_unknown_anchor_still_raises(self):+ base = [_step("a")]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("replace", "missing", _step("new"))],+ )+ with pytest.raises(ValueError, match="Anchor 'missing' not found"):+ merge_steps(base, [_layer(overlay, "project:ov")])++ # ββ composite step attribution βββββββββββββββββββββββββββββββββββββββ++ def test_merge_insert_composite_if_attribution(self):+ """Nested then/else children of an inserted 'if' step get the overlay source."""+ base = [_step("a")]+ composite = {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("then-a")],+ "else": [_step("else-b")],+ }+ overlay = Overlay(+ id="ov", extends="wf", priority=10,+ edits=[OverlayEdit("insert_after", "a", composite)],+ )+ _steps, attribution = merge_steps(+ base, [_layer(overlay, "project:ov")]+ )+ assert attribution == [+ ComposedStep("a", "base"),+ ComposedStep("if-1", "project:ov"),+ ComposedStep("then-a", "project:ov"),+ ComposedStep("else-b", "project:ov"),+ ]++ def test_merge_insert_composite_switch_attribution(self):+ """Nested cases/default children of an inserted 'switch' step get the overlay source."""+ base = [_step("a")]+ composite = {+ "id": "switch-1",+ "type": "switch",+ "expression": "{{inputs.x}}",+ "cases": {"one": [_step("case-one")], "two": [_step("case-two")]},+ "default": [_step("default-z")],+ }+ overlay = Overlay(+ id="ov", extends="wf", priority=10,+ edits=[OverlayEdit("insert_before", "a", composite)],+ )+ _steps, attribution = merge_steps(+ base, [_layer(overlay, "project:ov")]+ )+ assert attribution == [+ ComposedStep("switch-1", "project:ov"),+ ComposedStep("default-z", "project:ov"),+ ComposedStep("case-one", "project:ov"),+ ComposedStep("case-two", "project:ov"),+ ComposedStep("a", "base"),+ ]++ def test_merge_replace_flat_with_composite_attribution(self):+ """Replacing a flat step with a composite step attributes all nested children."""+ base = [_step("a")]+ composite = {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("inner-x"), _step("inner-y")],+ }+ overlay = Overlay(+ id="ov", extends="wf", priority=10,+ edits=[OverlayEdit("replace", "a", composite)],+ )+ _steps, attribution = merge_steps(+ base, [_layer(overlay, "project:ov")]+ )+ assert attribution == [+ ComposedStep("if-1", "project:ov"),+ ComposedStep("inner-x", "project:ov"),+ ComposedStep("inner-y", "project:ov"),+ ]++ def test_merge_remove_composite_step_cleans_nested_sources(self):+ """Removing a composite step also cleans its nested children from sources."""+ base = [+ {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [_step("then-a")],+ "else": [_step("else-b")],+ },+ _step("a"),+ ]+ overlay = Overlay(+ id="ov", extends="wf", priority=10,+ edits=[OverlayEdit("remove", "if-1")],+ )+ steps, attribution = merge_steps(+ base, [_layer(overlay, "project:ov")]+ )+ assert [s["id"] for s in steps] == ["a"]+ assert attribution == [ComposedStep("a", "base")]++ def test_merge_insert_deeply_nested_composite_attribution(self):+ """Deep nesting (if inside while) gets the overlay source at every level."""+ base = [_step("a")]+ inner_if = {+ "id": "inner-if",+ "type": "if",+ "condition": "true",+ "then": [_step("deep-x")],+ }+ composite = {+ "id": "while-1",+ "type": "while",+ "condition": "true",+ "steps": [inner_if],+ }+ overlay = Overlay(+ id="ov", extends="wf", priority=10,+ edits=[OverlayEdit("insert_after", "a", composite)],+ )+ _steps, attribution = merge_steps(+ base, [_layer(overlay, "project:ov")]+ )+ assert attribution == [+ ComposedStep("a", "base"),+ ComposedStep("while-1", "project:ov"),+ ComposedStep("inner-if", "project:ov"),+ ComposedStep("deep-x", "project:ov"),+ ]+++class TestValidateEdits:+ """Edit validation against known base step IDs."""++ def test_valid_edits(self):+ edits = [+ OverlayEdit("insert_after", "a", _step("new")),+ OverlayEdit("remove", "b"),+ ]+ assert validate_edits(edits, {"a", "b"}) == []++ def test_invalid_anchor(self):+ edits = [OverlayEdit("insert_after", "missing", _step("new"))]+ errors = validate_edits(edits, {"a"})+ assert any("missing" in e for e in errors)++ def test_step_id_contains_colon(self):+ edits = [OverlayEdit("insert_after", "a", _step("bad:id"))]+ errors = validate_edits(edits, {"a"})+ assert any("':'" in e for e in errors)++ def test_remove_requires_no_step(self):+ edits = [OverlayEdit("remove", "a", _step("extra"))]+ errors = validate_edits(edits, {"a"})+ assert len(errors) > 0+++class TestMergeStepsAncestorConflicts:+ """merge_steps raises when two targeted anchors are in a parent/descendant relationship."""++ def _if_step(self, parent_id: str, child_id: str) -> dict[str, Any]:+ return {+ "id": parent_id,+ "type": "if",+ "condition": "true",+ "then": [_step(child_id)],+ }++ def test_remove_parent_and_insert_after_child_raises(self):+ """Removing a parent while inserting after its nested child is an anchor conflict."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id)]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ OverlayEdit("remove", parent_id),+ OverlayEdit("insert_after", child_id, _step("new-step")),+ ],+ )+ with pytest.raises(ValueError, match="ancestor"):+ merge_steps(base, [_layer(overlay, "project:ov")])++ def test_replace_parent_and_remove_child_raises(self):+ """Replacing a parent while also removing a nested child is an anchor conflict."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id)]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ OverlayEdit("replace", parent_id, _step("new-parent")),+ OverlayEdit("remove", child_id),+ ],+ )+ with pytest.raises(ValueError, match="ancestor"):+ merge_steps(base, [_layer(overlay, "project:ov")])++ def test_conflict_across_multiple_overlays_raises(self):+ """Conflict is detected even when conflicting anchors come from different overlays."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id)]+ overlay_a = Overlay(+ id="ov-a",+ extends="wf",+ priority=5,+ edits=[OverlayEdit("remove", parent_id)],+ )+ overlay_b = Overlay(+ id="ov-b",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("insert_after", child_id, _step("new-step"))],+ )+ with pytest.raises(ValueError, match="ancestor"):+ merge_steps(+ base,+ [_layer(overlay_a, "project:ov-a"), _layer(overlay_b, "project:ov-b")],+ )++ def test_sibling_anchors_not_conflicting(self):+ """Anchors in sibling branches (not ancestor/descendant) are allowed."""+ base = [+ {+ "id": "if-step",+ "type": "if",+ "condition": "true",+ "then": [_step("then-child")],+ "else": [_step("else-child")],+ }+ ]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ OverlayEdit("insert_after", "then-child", _step("after-then")),+ OverlayEdit("insert_after", "else-child", _step("after-else")),+ ],+ )+ # Should not raise β the two anchors are siblings, not ancestor/descendant.+ steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])+ step_ids = [s.get("id") for s in steps[0]["then"]] + [s.get("id") for s in steps[0]["else"]]+ assert "after-then" in step_ids+ assert "after-else" in step_ids++ def test_single_anchor_not_conflicting(self):+ """A single anchor is never in conflict with itself."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id)]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[OverlayEdit("remove", parent_id)],+ )+ steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])+ assert steps == []++ def test_child_not_targeted_no_conflict(self):+ """Targeting a parent alone (child not in any edit) is allowed."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id), _step("other")]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ OverlayEdit("remove", parent_id),+ OverlayEdit("insert_after", "other", _step("new-step")),+ ],+ )+ # "other" is not inside "if-step", so no ancestor conflict.+ steps, _ = merge_steps(base, [_layer(overlay, "project:ov")])+ assert [s["id"] for s in steps] == ["other", "new-step"]++ def test_insert_only_on_ancestor_and_descendant_not_conflicting(self):+ """insert_after on both a parent and its nested child is valid and order-independent."""+ parent_id = "if-step"+ child_id = "then-child"+ base = [self._if_step(parent_id, child_id)]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ OverlayEdit("insert_after", parent_id, _step("after-parent")),+ OverlayEdit("insert_after", child_id, _step("after-child")),+ ],+ )+ # Should not raise β inserts leave the ancestor intact.+ steps, attribution = merge_steps(base, [_layer(overlay, "project:ov")])+ # "after-parent" is inserted at the top level after the if-step.+ assert [s["id"] for s in steps] == [parent_id, "after-parent"]+ # "after-child" is inserted inside the then list.+ then_ids = [s["id"] for s in steps[0]["then"]]+ assert then_ids == [child_id, "after-child"]+++class TestMergeStepsIdCollision:+ """merge_steps is deterministic when a replacement reuses a base step ID."""++ def test_replace_with_reused_id_does_not_affect_original(self):+ """Replacing A with new_step(id=B) must not interfere with editing original B.++ Before the fix, the remove-B anchor group would find the replacement step+ (which now has id='b') instead of the original 'b' step, producing a+ different result depending on dict iteration order.+ """+ base = [_step("a"), _step("b"), _step("c")]+ overlay = Overlay(+ id="ov",+ extends="wf",+ priority=10,+ edits=[+ # Replace "a" with a new step that reuses id "b".+ OverlayEdit("replace", "a", {**_step("b"), "command": "speckit.replaced"}),+ # Remove the original "b".+ OverlayEdit("remove", "b"),+ ],+ )+ steps, attribution = merge_steps(base, [_layer(overlay, "project:ov")])+ # The original "b" is removed; the replacement (also id="b") survives.+ # "c" is untouched.+ assert len(steps) == 2+ remaining_ids = [s["id"] for s in steps]+ assert remaining_ids == ["b", "c"]+ # The surviving "b" step is the replacement (has the custom command).+ assert steps[0]["command"] == "speckit.replaced"+ # Attribution for the surviving replacement "b" must not be "unknown".+ # Previously, removing original "b" would pop sources["b"], erasing the+ # attribution recorded for the replacement step (regression guard for the+ # _remove_sources_recursively-in-remove-branch bug).+ sources = {cs.step_id: cs.source for cs in attribution}+ assert sources.get("b") == "project:ov", (+ f"expected 'project:ov' but got {sources.get('b')!r}"+ )diff --git a/tests/workflows/test_overlay_schema.py b/tests/workflows/test_overlay_schema.pynew file mode 100644index 000000000..08813f853--- /dev/null+++ b/tests/workflows/test_overlay_schema.py@@ -0,0 +1,277 @@+"""Tests for overlay YAML schema normalization, especially shorthand edits."""++from __future__ import annotations++import pytest++from specify_cli.workflows.overlays.schema import (+ OverlayEdit,+ validate_overlay_yaml,+)+++class TestShorthandEdits:+ """Requirements-compliant shorthand edit format."""++ def test_shorthand_insert_after(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "lint",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "insert_after": "implement",+ "step": {"id": "lint", "type": "shell", "command": "npm run lint"},+ }+ ],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [+ OverlayEdit("insert_after", "implement", {"id": "lint", "type": "shell", "command": "npm run lint"})+ ]++ def test_shorthand_insert_before(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "insert_before": "a",+ "step": {"id": "b", "type": "command", "command": "echo"},+ }+ ],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [+ OverlayEdit("insert_before", "a", {"id": "b", "type": "command", "command": "echo"})+ ]++ def test_shorthand_replace(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "replace": "a",+ "step": {"id": "a", "type": "command", "command": "echo"},+ }+ ],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [+ OverlayEdit("replace", "a", {"id": "a", "type": "command", "command": "echo"})+ ]++ def test_shorthand_remove(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [OverlayEdit("remove", "a")]++ def test_explicit_operation_format_still_valid(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "b", "type": "command", "command": "echo"},+ }+ ],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [+ OverlayEdit("insert_after", "a", {"id": "b", "type": "command", "command": "echo"})+ ]++ def test_multiple_operation_fields_rejected(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "insert_after": "a",+ "remove": "a",+ }+ ],+ }+ )+ assert overlay is None+ assert any("multiple" in e.lower() for e in errors), errors++ def test_invalid_operation_field_rejected(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [{"destroy": "a"}],+ }+ )+ assert overlay is None+ assert any("operation" in e.lower() for e in errors), errors++ def test_shorthand_and_explicit_mixed_list(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {"insert_after": "a", "step": {"id": "b", "type": "command", "command": "echo"}},+ {+ "operation": "remove",+ "anchor": "c",+ },+ ],+ }+ )+ assert not errors, errors+ assert overlay is not None+ assert overlay.edits == [+ OverlayEdit("insert_after", "a", {"id": "b", "type": "command", "command": "echo"}),+ OverlayEdit("remove", "c"),+ ]++ def test_shorthand_remove_must_not_include_step(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "remove": "a",+ "step": {"id": "b", "type": "command", "command": "echo"},+ }+ ],+ }+ )+ assert overlay is None+ assert any("remove" in e.lower() and "step" in e.lower() for e in errors), errors+++class TestOverlayIdValidation:+ """Overlay and workflow IDs must be safe path segments."""++ @pytest.mark.parametrize("overlay_id", ["../ov", "a/b", "a\\\\b", ".", "..", ""])+ def test_invalid_overlay_id_rejected(self, overlay_id):+ overlay, errors = validate_overlay_yaml(+ {+ "id": overlay_id,+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert overlay is None+ assert any("id" in e.lower() for e in errors), errors+++class TestOverlayPriorityNormalization:+ """Stored overlay priorities match preset normalization semantics."""++ @pytest.mark.parametrize("priority", [None, True, "invalid", 0])+ def test_invalid_or_missing_priority_defaults_to_ten(self, priority):+ data = {+ "id": "ov",+ "extends": "wf",+ "edits": [{"remove": "a"}],+ }+ if priority is not None:+ data["priority"] = priority++ overlay, errors = validate_overlay_yaml(data)++ assert errors == []+ assert overlay is not None+ assert overlay.priority == 10++ @pytest.mark.parametrize("extends", ["../wf", "a/b", "a\\\\b", ".", "..", ""])+ def test_invalid_extends_rejected(self, extends):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": extends,+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert overlay is None+ assert any("extends" in e.lower() for e in errors), errors++ @pytest.mark.parametrize("extends", ["overlays", "runs", "steps"])+ def test_reserved_workflow_id_rejected(self, extends):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov",+ "extends": extends,+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert overlay is None+ assert any("reserved" in error.lower() for error in errors), errors++ def test_valid_dashed_id_accepted(self):+ overlay, errors = validate_overlay_yaml(+ {+ "id": "my-overlay",+ "extends": "my-workflow",+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert not errors, errors+ assert overlay is not None++ def test_validate_safe_id_rejects_trailing_newline(self):+ """A trailing newline must not pass ID validation (fullmatch guard)."""+ overlay, errors = validate_overlay_yaml(+ {+ "id": "overlay\n",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert overlay is None+ assert any("id" in e.lower() for e in errors), errors++ def test_validate_safe_id_rejects_embedded_newline(self):+ """An embedded newline must not pass ID validation."""+ overlay, errors = validate_overlay_yaml(+ {+ "id": "ov\nerlay",+ "extends": "wf",+ "priority": 10,+ "edits": [{"remove": "a"}],+ }+ )+ assert overlay is None+ assert any("id" in e.lower() for e in errors), errorsdiff --git a/tests/workflows/test_overlay_security.py b/tests/workflows/test_overlay_security.pynew file mode 100644index 000000000..a1249ad84--- /dev/null+++ b/tests/workflows/test_overlay_security.py@@ -0,0 +1,321 @@+"""Security tests for workflow overlay path handling."""++from __future__ import annotations++from pathlib import Path++import pytest+import yaml+from typer.testing import CliRunner++from specify_cli import app+++runner = CliRunner()+++def project_dir(tmp_path):+ """Create a mock spec-kit project with ``.specify/workflows/`` directory."""+ workflows_dir = tmp_path / ".specify" / "workflows"+ workflows_dir.mkdir(parents=True, exist_ok=True)+ return tmp_path+++def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:+ wf_dir = project_root / ".specify" / "workflows" / workflow_id+ wf_dir.mkdir(parents=True, exist_ok=True)+ wf_path = wf_dir / "workflow.yml"+ wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return wf_path+++def _write_overlay(project_root: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id+ ov_dir.mkdir(parents=True, exist_ok=True)+ ov_path = ov_dir / f"{overlay_id}.yml"+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return ov_path+++class TestOverlayPathTraversal:+ """Overlay CLI must stay inside the overlay directory."""++ def test_overlay_add_rejects_traversal_in_workflow_id(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "../wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]+ )+ assert result.exit_code != 0, result.output+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()++ def test_overlay_add_rejects_traversal_in_overlay_id(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "../../ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(+ app, ["workflow", "overlay", "add", str(overlay_file), "--priority", "5"]+ )+ assert result.exit_code != 0, result.output+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()++ def test_overlay_remove_cannot_escape_overlays_dir(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ # Create a base workflow file that would be the traversal target.+ target = project_dir / ".specify" / "workflows" / "wf" / "workflow.yml"+ assert target.is_file()++ result = runner.invoke(+ app, ["workflow", "overlay", "remove", "wf", "../wf/workflow"]+ )+ assert result.exit_code != 0, result.output+ assert target.is_file()+ assert "Invalid" in result.output or "traversal" in result.output.lower()++ def test_overlay_remove_rejects_symlink(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ real_file = overlay_dir / "ov1.yml"+ symlink_file = overlay_dir / "symlink.yml"+ symlink_file.symlink_to(real_file)++ result = runner.invoke(app, ["workflow", "overlay", "remove", "wf", "symlink"])+ assert result.exit_code != 0, result.output+ assert real_file.is_file()+ assert "symlink" in result.output.lower() or "Invalid" in result.output++ def test_overlay_add_rejects_symlinked_target_file(self, project_dir, monkeypatch):+ """overlay add must not overwrite through a symlinked overlay file target."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )++ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ overlay_dir.mkdir(parents=True, exist_ok=True)+ real_file = overlay_dir / "other.yml"+ real_file.write_text("sentinel\n", encoding="utf-8")+ (overlay_dir / "ov1.yml").symlink_to(real_file)++ overlay_file = project_dir / "overlay.yml"+ overlay_file.write_text(+ yaml.safe_dump(+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ result = runner.invoke(app, ["workflow", "overlay", "add", str(overlay_file)])++ assert result.exit_code != 0, result.output+ assert "symlinked path" in result.output.lower()+ assert real_file.read_text(encoding="utf-8") == "sentinel\n"++ @pytest.mark.parametrize("workflow_id", ["overlays", "runs", "steps"])+ def test_overlay_operations_reject_reserved_workflow_id(+ self, project_dir, monkeypatch, workflow_id+ ):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ result = runner.invoke(app, ["workflow", "overlay", "list", workflow_id])+ assert result.exit_code != 0, result.output+ assert "Invalid" in result.output or "reserved" in result.output.lower()++ def test_overlay_set_priority_rejects_traversal(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ result = runner.invoke(+ app, ["workflow", "overlay", "set-priority", "wf", "../other", "10"]+ )+ assert result.exit_code != 0, result.output+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()++ def test_overlay_enable_rejects_traversal(self, project_dir, monkeypatch):+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ result = runner.invoke(app, ["workflow", "overlay", "enable", "wf", "../other"])+ assert result.exit_code != 0, result.output+ assert "invalid" in result.output.lower() or "traversal" in result.output.lower()++ def test_overlay_rejects_symlinked_overlays_dir(self, project_dir, monkeypatch, tmp_path):+ """Overlay commands must reject a symlinked .specify/workflows/overlays directory."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)++ # Create a symlinked overlays directory pointing outside the project+ outside_dir = tmp_path / "outside"+ outside_dir.mkdir()+ overlays_dir = project_dir / ".specify" / "workflows" / "overlays"+ overlays_dir.symlink_to(outside_dir)++ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])+ assert result.exit_code != 0, result.output+ assert "symlink" in result.output.lower()++ def test_overlay_list_rejects_symlinked_per_workflow_dir(self, project_dir, monkeypatch, tmp_path):+ """Overlay list must reject a symlinked per-workflow overlay directory."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)++ # Create a real overlay directory outside the project.+ outside_dir = tmp_path / "outside_wf"+ outside_dir.mkdir()+ outside_dir.joinpath("evil.yml").write_text(+ yaml.safe_dump(+ {+ "id": "evil",+ "extends": "wf",+ "priority": 100,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "evil-step", "type": "command", "command": "echo"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ # Symlink the per-workflow overlay directory to the outside location.+ overlays_root = project_dir / ".specify" / "workflows" / "overlays"+ overlays_root.mkdir(parents=True, exist_ok=True)+ symlink_dir = overlays_root / "wf"+ symlink_dir.symlink_to(outside_dir)++ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])+ assert result.exit_code != 0, result.output+ assert "symlink" in result.output.lower()++ def test_overlay_list_reports_invalid_yaml_cleanly(self, project_dir, monkeypatch):+ """Overlay list should surface malformed overlay YAML as a clean user error."""+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)+ _write_workflow(+ project_dir,+ "wf",+ {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "echo"}],+ },+ )+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ overlay_dir.mkdir(parents=True, exist_ok=True)+ (overlay_dir / "broken.yml").write_text("id: broken\nextends: wf\npriority: [\n", encoding="utf-8")++ result = runner.invoke(app, ["workflow", "overlay", "list", "wf"])++ assert result.exit_code != 0, result.output+ assert "Invalid YAML" in result.outputdiff --git a/tests/workflows/test_resolver_integration.py b/tests/workflows/test_resolver_integration.pynew file mode 100644index 000000000..6f6ab9d65--- /dev/null+++ b/tests/workflows/test_resolver_integration.py@@ -0,0 +1,567 @@+"""Integration tests for the WorkflowResolver."""++from __future__ import annotations++from pathlib import Path++import pytest+import yaml++from specify_cli.workflows.engine import WorkflowDefinition, validate_workflow+from specify_cli.workflows.overlays import WorkflowResolver+from specify_cli.workflows.overlays.merge import ComposedStep+++def _write_workflow(project_root: Path, workflow_id: str, data: dict) -> Path:+ wf_dir = project_root / ".specify" / "workflows" / workflow_id+ wf_dir.mkdir(parents=True, exist_ok=True)+ wf_path = wf_dir / "workflow.yml"+ wf_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return wf_path+++def _write_overlay(project_root: Path, workflow_id: str, overlay_id: str, data: dict) -> Path:+ ov_dir = project_root / ".specify" / "workflows" / "overlays" / workflow_id+ ov_dir.mkdir(parents=True, exist_ok=True)+ ov_path = ov_dir / f"{overlay_id}.yml"+ ov_path.write_text(yaml.safe_dump(data), encoding="utf-8")+ return ov_path+++class TestWorkflowResolver:+ """End-to-end resolution of base workflows plus overlays."""++ @pytest.mark.parametrize(+ "workflow_id",+ [+ "../outside",+ "nested/workflow",+ "wf\n",+ "overlays",+ "runs",+ "steps",+ ],+ )+ def test_rejects_unsafe_id_before_collecting_sources(+ self, project_dir, workflow_id+ ):+ resolver = WorkflowResolver(project_dir)++ class UnexpectedSource:+ def collect(self, _workflow_id):+ pytest.fail("source collection must not run for an unsafe workflow ID")++ resolver._sources = [UnexpectedSource()]++ with pytest.raises(ValueError, match="Invalid workflow ID"):+ resolver.resolve(workflow_id)++ def test_rejects_absolute_id_before_collecting_sources(+ self, project_dir, tmp_path+ ):+ resolver = WorkflowResolver(project_dir)+ outside = tmp_path / "outside"++ class UnexpectedSource:+ def collect(self, _workflow_id):+ pytest.fail("source collection must not run for an absolute workflow ID")++ resolver._sources = [UnexpectedSource()]++ with pytest.raises(ValueError, match="Invalid workflow ID"):+ resolver.resolve(str(outside))++ def test_resolve_without_overlays(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)++ resolver = WorkflowResolver(project_dir)+ definition = resolver.resolve("wf")+ assert isinstance(definition, WorkflowDefinition)+ assert definition.id == "wf"+ assert [s["id"] for s in definition.steps] == ["a"]++ def test_resolve_with_project_overlay_insert(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [+ {"id": "a", "type": "command", "command": "speckit.specify"},+ {"id": "b", "type": "command", "command": "speckit.specify"},+ ],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "speckit.plan"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ definition = resolver.resolve("wf")+ assert [s["id"] for s in definition.steps] == ["a", "new", "b"]++ def test_resolve_lower_priority_wins(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "low",+ {+ "id": "low",+ "extends": "wf",+ "priority": 5,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "low-step", "type": "command", "command": "echo"},+ }+ ],+ },+ )+ _write_overlay(+ project_dir,+ "wf",+ "high",+ {+ "id": "high",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "high-step", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ definition = resolver.resolve("wf")+ # Lower priority is applied later; both insert_after 'a', so low-step+ # ends up closer to the anchor and wins the conflict.+ assert [s["id"] for s in definition.steps] == ["a", "low-step", "high-step"]++ def test_resolve_with_layers_returns_attribution(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ definition, layers, attribution = resolver.resolve_with_layers("wf")+ assert [s["id"] for s in definition.steps] == ["a", "new"]+ assert any(layer.tier == "base" for layer in layers)+ assert attribution == [ComposedStep("a", "base"), ComposedStep("new", "project:ov1")]++ def test_resolve_attribution_for_nested_base_steps(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [+ {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [{"id": "then-a", "type": "command", "command": "echo"}],+ "else": [{"id": "else-b", "type": "command", "command": "echo"}],+ }+ ],+ }+ _write_workflow(project_dir, "wf", data)++ resolver = WorkflowResolver(project_dir)+ definition, _layers, attribution = resolver.resolve_with_layers("wf")+ assert [s["id"] for s in definition.steps] == ["if-1"]+ sources = {c.step_id: c.source for c in attribution}+ assert sources["if-1"] == "base"+ assert sources["then-a"] == "base"+ assert sources["else-b"] == "base"++ def test_resolve_invalid_project_overlay_fails(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "broken",+ {+ "id": "broken",+ "extends": "wf",+ "priority": 10,+ "edits": "not-a-list",+ },+ )++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError):+ resolver.resolve("wf")++ def test_resolve_disabled_overlay_is_skipped(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "disabled",+ {+ "id": "disabled",+ "extends": "wf",+ "priority": 10,+ "enabled": False,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ definition = resolver.resolve("wf")+ assert [s["id"] for s in definition.steps] == ["a"]++ def test_collect_all_layers_can_include_disabled_overlay_for_listing(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "disabled",+ {+ "id": "disabled",+ "extends": "wf",+ "priority": 10,+ "enabled": False,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ default_layers = resolver.collect_all_layers("wf")+ listed_layers = resolver.collect_all_layers("wf", include_disabled=True)++ assert [layer.source for layer in default_layers] == ["base"]+ assert [layer.source for layer in listed_layers] == ["project:disabled", "base"]++ def test_resolve_invalid_anchor_raises(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "missing",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError, match="anchor 'missing' does not match any base step id"):+ resolver.resolve("wf")++ def test_resolve_missing_workflow(self, project_dir):+ resolver = WorkflowResolver(project_dir)+ with pytest.raises(FileNotFoundError, match="Workflow not found"):+ resolver.resolve("missing")++ def test_resolve_returns_composed_result_for_caller_validation(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "replace",+ "anchor": "a",+ "step": {"id": "a", "type": "invalid-type", "command": "echo"},+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ definition = resolver.resolve("wf")+ errors = validate_workflow(definition)+ assert any("invalid-type" in err for err in errors)++ def test_resolve_rejects_symlinked_project_overlay_dir(self, project_dir, tmp_path):+ """ProjectOverlaySource must reject a symlinked per-workflow overlay directory."""+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)++ # Create a real overlay directory outside the project with a malicious overlay.+ outside_dir = tmp_path / "outside_overlays" / "wf"+ outside_dir.mkdir(parents=True, exist_ok=True)+ outside_dir.joinpath("evil.yml").write_text(+ yaml.safe_dump(+ {+ "id": "evil",+ "extends": "wf",+ "priority": 100,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "evil-step", "type": "command", "command": "rm -rf /"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ # Symlink the per-workflow overlay directory to the outside location.+ overlays_root = project_dir / ".specify" / "workflows" / "overlays"+ overlays_root.mkdir(parents=True, exist_ok=True)+ symlink_dir = overlays_root / "wf"+ symlink_dir.symlink_to(outside_dir)++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError, match="Symlinked overlay directories are not allowed"):+ resolver.resolve("wf")++ def test_resolve_rejects_symlinked_overlay_root(self, project_dir, tmp_path):+ """ProjectOverlaySource must reject a symlinked overlay root too."""+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)++ outside_root = tmp_path / "outside-overlays-root"+ outside_root.mkdir(parents=True, exist_ok=True)+ workflow_dir = outside_root / "wf"+ workflow_dir.mkdir()+ workflow_dir.joinpath("evil.yml").write_text(+ yaml.safe_dump(+ {+ "id": "evil",+ "extends": "wf",+ "priority": 100,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "evil-step", "type": "command", "command": "rm -rf /"},+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ overlays_root = project_dir / ".specify" / "workflows" / "overlays"+ overlays_root.symlink_to(outside_root, target_is_directory=True)++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError, match="Symlinked overlay directories are not allowed"):+ resolver.resolve("wf")++ def test_resolve_reports_invalid_overlay_yaml_cleanly(self, project_dir):+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ overlay_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"+ overlay_dir.mkdir(parents=True, exist_ok=True)+ (overlay_dir / "broken.yml").write_text("id: broken\nextends: wf\npriority: [\n", encoding="utf-8")++ resolver = WorkflowResolver(project_dir)+ with pytest.raises(ValueError, match="Invalid YAML"):+ resolver.resolve("wf")++ def test_resolve_attribution_for_inserted_composite_step(self, project_dir):+ """Inserted composite steps must attribute nested children to the overlay source."""+ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {+ "id": "if-1",+ "type": "if",+ "condition": "true",+ "then": [{"id": "then-x", "type": "command", "command": "echo"}],+ "else": [{"id": "else-y", "type": "command", "command": "echo"}],+ },+ }+ ],+ },+ )++ resolver = WorkflowResolver(project_dir)+ _definition, _layers, attribution = resolver.resolve_with_layers("wf")+ sources = {c.step_id: c.source for c in attribution}+ assert sources["a"] == "base"+ assert sources["if-1"] == "project:ov1"+ assert sources["then-x"] == "project:ov1"+ assert sources["else-y"] == "project:ov1"++ def test_engine_load_workflow_uses_resolver(self, project_dir):+ from specify_cli.workflows.engine import WorkflowEngine++ data = {+ "schema_version": "1.0",+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},+ "steps": [{"id": "a", "type": "command", "command": "speckit.specify"}],+ }+ _write_workflow(project_dir, "wf", data)+ _write_overlay(+ project_dir,+ "wf",+ "ov1",+ {+ "id": "ov1",+ "extends": "wf",+ "priority": 10,+ "edits": [+ {+ "operation": "insert_after",+ "anchor": "a",+ "step": {"id": "new", "type": "command", "command": "echo"},+ }+ ],+ },+ )++ engine = WorkflowEngine(project_dir)+ definition = engine.load_workflow("wf")+ assert [s["id"] for s in definition.steps] == ["a", "new"]++ def test_engine_rejects_traversal_without_legacy_path_fallback(+ self, project_dir+ ):+ from specify_cli.workflows.engine import WorkflowEngine++ outside = project_dir / ".specify" / "outside"+ outside.mkdir(parents=True)+ (outside / "workflow.yml").write_text(+ yaml.safe_dump(+ {+ "schema_version": "1.0",+ "workflow": {+ "id": "outside",+ "name": "Outside",+ "version": "1.0.0",+ },+ "steps": [+ {+ "id": "external",+ "type": "command",+ "command": "echo",+ }+ ],+ }+ ),+ encoding="utf-8",+ )++ engine = WorkflowEngine(project_dir)+ with pytest.raises(ValueError, match="Invalid workflow ID"):+ engine.load_workflow("../outside")