Skip to content

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

fix(workflows): refuse `overlay add` that would overwrite a different overlay (#4141)

Ali jawwadd7dfe4360648
diff --git a/src/specify_cli/workflows/overlays/_commands.py b/src/specify_cli/workflows/overlays/_commands.py
index 06c4dca83..156e0d6c0 100644
--- a/src/specify_cli/workflows/overlays/_commands.py
+++ b/src/specify_cli/workflows/overlays/_commands.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import os
from pathlib import Path
from typing import Any
@@ -207,6 +208,51 @@ def workflow_overlay_add(
target_path = _ensure_contained_path(
target_dir / f"{overlay.id}.yml", _overlay_root(project_root)
)
+ # Overlay identity is the manifest ``id``, not the filename (see
+ # ``_find_overlay_file``), so ``<id>.yml`` can legitimately already hold
+ # a DIFFERENT overlay. Committing onto it would destroy that overlay
+ # permanently -- the commit renames the victim to a ``.bak`` and the
+ # success path then discards that backup -- while reporting success.
+ # ``lexists`` rather than ``is_file``: the latter is False for a
+ # directory, FIFO or socket, so those bypassed this guard entirely and
+ # reached ``_commit_workflow_file``, which renames whatever is there to
+ # a ``.bak`` sibling and then discards it on the success path. A
+ # directory occupant was moved aside and the command still reported
+ # success -- it survived only because unlinking a directory happens to
+ # fail. A FIFO or socket has no such accident and is simply gone.
+ if os.path.lexists(target_path):
+ if target_path.is_symlink() or not target_path.is_file():
+ err_console.print(
+ f"[red]Error:[/red] {_escape_markup(str(target_path))} exists "
+ f"and is not a regular file. Rename or remove it before "
+ f"adding overlay {_escape_markup(repr(overlay.id))}."
+ )
+ return None
+ # Fail closed: refuse unless the occupant is provably this same
+ # overlay. Reaching here means ``_find_overlay_file`` did not match
+ # this path, and it skips exactly the files whose identity cannot be
+ # established -- unreadable, malformed, non-mapping, or missing a
+ # usable ``id``. Letting those through would destroy the user's file
+ # just as permanently as overwriting a valid one, only without even
+ # being able to name what was lost.
+ occupant, read_errors = _read_overlay(target_path)
+ occupant_id = occupant.get("id") if isinstance(occupant, dict) else None
+ if not (isinstance(occupant_id, str) and occupant_id == overlay.id):
+ if isinstance(occupant_id, str) and occupant_id:
+ detail = f"already holds overlay {_escape_markup(repr(occupant_id))}"
+ elif read_errors:
+ detail = (
+ "could not be parsed as an overlay "
+ f"({_escape_markup('; '.join(read_errors))})"
+ )
+ else:
+ detail = "is not a readable overlay manifest (no usable 'id')"
+ err_console.print(
+ f"[red]Error:[/red] {_escape_markup(str(target_path))} {detail}. "
+ f"Rename or remove it before adding overlay "
+ f"{_escape_markup(repr(overlay.id))}."
+ )
+ return None
backup: Path | None = None
try:
diff --git a/tests/workflows/test_overlay_commands.py b/tests/workflows/test_overlay_commands.py
index c28f53b05..8ac8d0663 100644
--- a/tests/workflows/test_overlay_commands.py
+++ b/tests/workflows/test_overlay_commands.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import os
from pathlib import Path
import pytest
@@ -1002,3 +1003,170 @@ class TestOverlayFilenameVsManifestId:
with pytest.raises(typer.Exit):
_find_overlay_file(project_dir, "wf", "lint")
+
+
+class TestOverlayAddDoesNotClobber:
+ """`overlay add` must not destroy a different overlay sitting at <id>.yml.
+
+ Overlay identity is the manifest `id`, not the filename (see
+ `_find_overlay_file`), so `lint.yml` can legitimately contain
+ `id: format`. When `_find_overlay_file` found no file carrying the new
+ overlay's id, the fallback target was derived purely from the filename and
+ committed onto unconditionally β€” permanently destroying the occupant, since
+ the commit renames it to a `.bak` and the success path then discards that
+ backup. Exit code 0, no warning.
+ """
+
+ def _setup(self, project_dir: Path, occupant_id: str | None) -> tuple[Path, Path]:
+ _write_workflow(
+ project_dir,
+ "wf",
+ {
+ "schema_version": "1.0",
+ "workflow": {"id": "wf", "name": "WF", "version": "1.0.0"},
+ "steps": [{"id": "a", "type": "command", "command": "echo"}],
+ },
+ )
+ ov_dir = project_dir / ".specify" / "workflows" / "overlays" / "wf"
+ ov_dir.mkdir(parents=True, exist_ok=True)
+ if occupant_id is not None:
+ (ov_dir / "lint.yml").write_text(
+ yaml.safe_dump(
+ {
+ "id": occupant_id,
+ "extends": "wf",
+ "priority": 3,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ incoming = project_dir / "incoming.yml"
+ incoming.write_text(
+ yaml.safe_dump(
+ {
+ "id": "lint",
+ "extends": "wf",
+ "priority": 10,
+ "edits": [{"remove": "a"}],
+ }
+ ),
+ encoding="utf-8",
+ )
+ return ov_dir, incoming
+
+ def test_add_does_not_clobber_a_different_overlay(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id="format")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ # The victim must be untouched, and no backup left lying around.
+ survivor = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
+ assert survivor["id"] == "format", survivor
+ assert survivor["priority"] == 3, survivor
+ assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
+
+ def test_add_still_updates_the_same_overlay_in_place(
+ self, project_dir, monkeypatch
+ ):
+ """The guard must only fire for a *different* overlay id."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id="lint")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 0, result.output
+ updated = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
+ assert updated["id"] == "lint"
+ assert updated["priority"] == 10
+
+ def test_add_refuses_a_directory_occupant(self, project_dir, monkeypatch):
+ """A non-regular occupant must be refused, not renamed aside.
+
+ The guard used `Path.is_file()`, which is False for a directory (and on
+ POSIX for a FIFO or socket), so such a destination bypassed it entirely
+ and reached `_commit_workflow_file` -- which renames whatever is there
+ to a `.bak` sibling and discards it on the success path. The command
+ reported success while moving the user's directory away; it survived
+ only because unlinking a directory happens to fail.
+ """
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = ov_dir / "lint.yml"
+ occupant.mkdir()
+ (occupant / "precious.txt").write_text("user data", encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ # Rich wraps console output, so normalise whitespace before matching.
+ assert "not a regular file" in " ".join(result.output.split())
+ # Untouched, still a directory, contents intact, nothing renamed aside.
+ assert occupant.is_dir()
+ assert (occupant / "precious.txt").read_text(encoding="utf-8") == "user data"
+ assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
+
+ @pytest.mark.skipif(
+ not hasattr(os, "mkfifo"), reason="FIFOs are POSIX-only"
+ )
+ def test_add_refuses_a_fifo_occupant(self, project_dir, monkeypatch):
+ """A FIFO has no accidental protection: it is renamed aside and deleted."""
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = ov_dir / "lint.yml"
+ os.mkfifo(occupant)
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ assert "not a regular file" in " ".join(result.output.split())
+ assert occupant.is_fifo()
+ assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
+
+ @pytest.mark.parametrize(
+ "raw",
+ [
+ "id: [1, 2\n bad: yaml:\n",
+ "- just\n- a\n- sequence\n",
+ "just a scalar\n",
+ "extends: wf\npriority: 3\n",
+ "id: 5\nextends: wf\npriority: 3\n",
+ ],
+ ids=["malformed", "sequence", "scalar", "missing_id", "non_string_id"],
+ )
+ def test_add_fails_closed_when_the_occupant_cannot_be_identified(
+ self, project_dir, monkeypatch, raw
+ ):
+ """An unidentifiable occupant must be refused, not silently destroyed.
+
+ `_find_overlay_file` matches on the manifest `id` and skips exactly the
+ files whose identity cannot be established β€” unreadable, malformed,
+ non-mapping, or missing a usable `id`. Those therefore fall through to
+ the filename-derived target, so a guard that only refuses a *different
+ valid* id would still let `_commit_workflow_file` discard the user's
+ file. It is destroyed just as permanently as a valid overlay, only
+ without even being able to name what was lost.
+ """
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id=None)
+ occupant = ov_dir / "lint.yml"
+ occupant.write_text(raw, encoding="utf-8")
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 1, result.output
+ # Byte-for-byte survival, and no backup left behind.
+ assert occupant.read_text(encoding="utf-8") == raw
+ assert [p.name for p in ov_dir.iterdir() if "bak" in p.name] == []
+
+ def test_add_creates_the_file_when_absent(self, project_dir, monkeypatch):
+ monkeypatch.setattr("specify_cli._require_specify_project", lambda: project_dir)
+ ov_dir, incoming = self._setup(project_dir, occupant_id=None)
+
+ result = runner.invoke(app, ["workflow", "overlay", "add", str(incoming)])
+
+ assert result.exit_code == 0, result.output
+ created = yaml.safe_load((ov_dir / "lint.yml").read_text(encoding="utf-8"))
+ assert created["id"] == "lint"