Skip to content

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

fix: make bundle step refresh rollback transactional (#4827)

Matt Van Horne9ebeeaec6bd
diff --git a/src/specify_cli/bundles/_commands.py b/src/specify_cli/bundles/_commands.py
index 512773b66..208cfff2e 100644
--- a/src/specify_cli/bundles/_commands.py
+++ b/src/specify_cli/bundles/_commands.py
@@ -46,6 +46,13 @@ def _fail(message: str, *, as_json: bool = False) -> None:
raise typer.Exit(code=1)
+def _fail_with_notes(exc: BaseException) -> None:
+ """Exit with the original error first, then any recovery notes."""
+ notes = [str(note) for note in getattr(exc, "__notes__", ())]
+ message = str(exc) if not notes else f"{exc}\n" + "\n".join(notes)
+ _fail(message)
+
+
def _render_install_warnings(result: InstallResult) -> None:
for warning in result.warnings:
err_console.print(f"[yellow]Warning:[/yellow] {_escape_markup(warning.message)}")
diff --git a/src/specify_cli/bundles/command_install.py b/src/specify_cli/bundles/command_install.py
index 877adff55..17d7a7069 100644
--- a/src/specify_cli/bundles/command_install.py
+++ b/src/specify_cli/bundles/command_install.py
@@ -13,7 +13,7 @@ from ._commands import (
_build_stack,
_bundle_overlaps,
_default_script_type,
- _fail,
+ _fail_with_notes,
_render_install_warnings,
_resolve_init_integration,
_run_init,
@@ -141,7 +141,7 @@ def bundle_install(
refresh=refresh,
)
except BundlerError as exc:
- _fail(str(exc))
+ _fail_with_notes(exc)
return
_render_install_warnings(result)
diff --git a/src/specify_cli/bundles/command_update.py b/src/specify_cli/bundles/command_update.py
index db4d54ada..ee999c97b 100644
--- a/src/specify_cli/bundles/command_update.py
+++ b/src/specify_cli/bundles/command_update.py
@@ -9,7 +9,7 @@ from .._console import console
from . import BundlerError
from ._commands import (
_build_stack,
- _fail,
+ _fail_with_notes,
_render_install_warnings,
_speckit_version,
bundle_app,
@@ -72,5 +72,5 @@ def bundle_update(
f"to v{_escape_markup(str(plan.version))}."
)
except BundlerError as exc:
- _fail(str(exc))
+ _fail_with_notes(exc)
return
diff --git a/src/specify_cli/bundles/primitives.py b/src/specify_cli/bundles/primitives.py
index 51206a853..f91059225 100644
--- a/src/specify_cli/bundles/primitives.py
+++ b/src/specify_cli/bundles/primitives.py
@@ -641,55 +641,154 @@ class _StepKindManager:
) from exc
def refresh(self, component: ComponentRef) -> None:
- # Preserve an existing step until we've validated we can perform refresh.
- # For already-installed steps, keep a backup and restore it if the
- # remove+reinstall path fails.
- if not (self._allow_network and self.is_installed(component)):
+ # Only offline refresh can skip the lock. Online presence is the
+ # registry read under ``_step_install_transaction``: a step added
+ # after this manager was constructed is still refreshed, and a step
+ # missing from that read delegates to ``install`` below.
+ if not self._allow_network:
self.install(component)
return
+ import copy
import shutil
import tempfile
- step_dir = self._registry.steps_dir / component.id
- metadata = self._registry.get(component.id)
- backup_dir = Path(tempfile.mkdtemp(prefix="speckit-step-refresh-")) / component.id
+ from ..workflows.catalog import StepRegistry
+ from ..workflows.step import command_remove
+ from ..workflows.step import installer as step_installer
+
+ # Snapshot and removal share the lock ``step add`` / ``step remove``
+ # already use. ``self.remove()`` and ``workflow_step_remove`` acquire
+ # that same lock, and ``_exclusive_project_lock`` blocks in
+ # ``fcntl.flock(LOCK_EX)`` on a new fd, so a nested acquire in this
+ # process deadlocks. Remove through ``_remove_step_locked`` instead.
+ # The catalog reinstall stays outside the lock. A step missing from
+ # the locked snapshot has nothing to roll back: release the lock and
+ # delegate to ``install``, which acquires this same lock.
+ backup_root: Path | None = None
+ keep_backup = False
+ metadata = None
+ had_snapshot = False
+ removal_error: BundlerError | None = None
try:
- if step_dir.exists():
- shutil.copytree(step_dir, backup_dir)
- self.remove(component)
try:
+ with step_installer._step_install_transaction(self._root):
+ registry = StepRegistry(self._root)
+ # ``get()`` is None for a JSON null entry and for an absent
+ # id. Installed-ness is key membership; snapshot the value
+ # separately so a null can be restored verbatim.
+ if registry.is_installed(component.id):
+ had_snapshot = True
+ metadata = copy.deepcopy(registry.get(component.id))
+ backup_root = Path(
+ tempfile.mkdtemp(prefix="speckit-step-refresh-")
+ )
+ backup_dir = backup_root / component.id
+ step_dir = registry.steps_dir / component.id
+ if step_dir.exists():
+ shutil.copytree(step_dir, backup_dir)
+ try:
+ _delegate_command(
+ "remove",
+ f"step '{component.id}'",
+ lambda: command_remove._remove_step_locked(
+ self._root, component.id
+ ),
+ )
+ except BundlerError as exc:
+ # ``_remove_step_locked`` drops the registry key
+ # before the directory delete. A JSON null cannot
+ # be put back there, so this error must reach
+ # rollback below with the snapshot still intact.
+ removal_error = exc
+ except step_installer.StepInstallError as exc:
+ # Lock acquisition failed before any package or registry snapshot.
+ raise BundlerError(
+ f"Failed to refresh step '{component.id}': {exc}"
+ ) from exc
+
+ if not had_snapshot:
self.install(component)
- except BundlerError:
- if backup_dir.exists():
- shutil.copytree(backup_dir, step_dir, dirs_exist_ok=True)
- # Re-read the registry: ``StepRegistry`` snapshots the file once
- # in ``__init__`` (``self.data = self._load()``) and
- # ``is_installed`` only consults that snapshot. ``self.remove()``
- # above has already deleted the entry from disk, but
- # ``self._registry``'s snapshot still contains it -- so the
- # guard was always False here and the restore never ran, in
- # exactly the failure case it was written for. The step package
- # came back but stayed unregistered: ``workflow step list``
- # stopped showing it and ``workflow step add`` then refused with
- # "Step directory already exists".
- from ..workflows.catalog import StepRegistry
-
- current = StepRegistry(self._root)
- if metadata is not None and not current.is_installed(component.id):
- # Restore the saved entry verbatim rather than via ``add()``,
- # which would rewrite the metadata it is meant to roll back:
- # this registry is freshly constructed *after*
- # ``self.remove()`` deleted the entry, so ``add()`` sees no
- # existing record and stamps ``installed_at`` with
- # ``datetime.now()`` (it also overwrites ``updated_at``
- # unconditionally). ``workflow_step_remove`` bypasses
- # ``add()`` for exactly this reason.
- current.data["steps"][component.id] = metadata
- current.save()
+ return
+
+ try:
+ if removal_error is not None:
+ raise removal_error
+ self.install(component)
+ except BundlerError as original:
+ try:
+ with step_installer._step_install_transaction(self._root):
+ assert backup_root is not None
+ backup_dir = backup_root / component.id
+ # Reinstall runs outside the lock, so the steps tree or
+ # the registry file can be swapped for a symlink before
+ # this section. ``_load`` returns an empty registry for
+ # a symlinked registry file or parent and does not
+ # raise. Resolve the steps base, then reject that
+ # symlink before deleting or copying the package.
+ # ``save()`` replaces the whole file: the document is
+ # that guarded read plus this step's snapshot when the
+ # id is absent. A later operation's package and registry
+ # keys are left alone.
+ current = StepRegistry(self._root)
+ loaded = current._load()
+ if not isinstance(loaded, dict):
+ document = {
+ "schema_version": StepRegistry.SCHEMA_VERSION,
+ "steps": {},
+ }
+ else:
+ document = loaded
+ if not isinstance(document.get("steps"), dict):
+ document["steps"] = {}
+ steps = document["steps"]
+ if component.id not in steps:
+ steps_base = step_installer.resolve_steps_base_dir(
+ self._root
+ )
+ step_dir = step_installer._resolve_step_dir(
+ steps_base, component.id
+ )
+ step_installer._reject_unsafe_destination(step_dir)
+ current.data = document
+ step_installer._check_duplicate(
+ current, component.id, step_dir, force=True
+ )
+ if (
+ current._has_symlinked_parent()
+ or current.registry_path.is_symlink()
+ ):
+ raise step_installer.StepInstallError(
+ "Refusing to restore step "
+ f"'{component.id}' through a symlinked "
+ "step registry at "
+ f"'{current.registry_path}'."
+ )
+ if step_dir.exists():
+ shutil.rmtree(step_dir)
+ if backup_dir.exists():
+ shutil.copytree(backup_dir, step_dir)
+ if had_snapshot:
+ # Insert the snapshot verbatim, including JSON
+ # null (``None``). ``StepRegistry.add`` would
+ # rewrite ``installed_at`` and ``updated_at``.
+ steps[component.id] = metadata
+ current.data = document
+ current.save()
+ except Exception as restore_exc: # noqa: BLE001
+ # The install error is what the caller handles. A failed
+ # copy-back or registry write is recorded on it, and the
+ # temp backup stays on disk for recovery.
+ keep_backup = True
+ original.add_note(
+ f"Could not restore step '{component.id}' from backup "
+ f"'{backup_root}': {restore_exc}"
+ )
+ # Bare ``raise`` keeps the install error's ``__cause__``.
raise
finally:
- shutil.rmtree(backup_dir.parent, ignore_errors=True)
+ if backup_root is not None and not keep_backup:
+ shutil.rmtree(backup_root, ignore_errors=True)
def remove(self, component: ComponentRef) -> None:
from .. import workflow_step_remove
diff --git a/tests/specify_cli/bundles/test_commands.py b/tests/specify_cli/bundles/test_commands.py
index 57ae60c72..d6ae45b52 100644
--- a/tests/specify_cli/bundles/test_commands.py
+++ b/tests/specify_cli/bundles/test_commands.py
@@ -109,3 +109,88 @@ def test_error_paths_escape_rich_markup(project: Path, argv: list, expected: str
# A MarkupError would surface here as an exception rather than a clean exit.
assert isinstance(result.exception, SystemExit)
assert expected in strip_ansi(result.output)
+
+
+ ("argv", "target"),
+ [
+ (
+ ["bundle", "install", "demo"],
+ "specify_cli.bundles.project.find_project_root",
+ ),
+ (
+ ["bundle", "update", "demo"],
+ "specify_cli.bundles.command_update.require_project_root",
+ ),
+ ],
+)
+def test_refresh_cli_shows_restoration_notes(monkeypatch, argv, target):
+ """``bundle install`` and ``bundle update`` show notes after the error."""
+ from specify_cli.bundles import BundlerError
+
+ def _boom(*_args, **_kwargs):
+ exc = BundlerError("primary failure")
+ exc.add_note("Could not restore step 'my-step' from backup '/tmp/bak'")
+ raise exc
+
+ monkeypatch.setattr(target, _boom)
+ result = runner.invoke(app, argv)
+ output = " ".join(strip_ansi(result.output).split())
+ assert result.exit_code == 1, result.output
+ assert "Error:" in output
+ assert "primary failure" in output
+ assert "Could not restore step 'my-step'" in output
+ assert "/tmp/bak" in output
+ assert output.index("primary failure") < output.index("Could not restore")
+
+
+def test_update_cli_shows_notes_from_real_install_bundle_refresh(
+ project: Path, monkeypatch
+):
+ """A refresh error's notes survive ``install_bundle`` and reach the CLI.
+
+ ``install_bundle`` runs for real here: only the primitive installer is
+ faked, and its step refresh fails the way a failed rollback does (the
+ install error first, the restoration failure as a note).
+ """
+ from types import SimpleNamespace
+
+ from specify_cli.bundles import BundlerError, adapters, command_update
+ from specify_cli.bundles.manifest import BundleManifest, ComponentRef
+ from specify_cli.bundles.records import InstalledBundleRecord, save_records
+ from tests.specify_cli.bundles.helpers import FakeInstaller, valid_manifest_dict
+
+ data = valid_manifest_dict(provides={"steps": [{"id": "my-step"}]})
+ manifest = BundleManifest.from_dict(data)
+ step = ComponentRef(kind="steps", id="my-step")
+ save_records(project, [
+ InstalledBundleRecord.create(manifest.bundle.id, manifest.bundle.version, [step]),
+ ])
+
+ class _RollbackFailingInstaller(FakeInstaller):
+ def refresh(self, project_root, component):
+ super().refresh(project_root, component)
+ exc = BundlerError(f"Failed to install step '{component.id}'.")
+ exc.add_note(
+ f"Could not restore step '{component.id}' from backup "
+ "'/tmp/speckit-step-refresh-x': restore copy failed"
+ )
+ raise exc
+
+ fake = _RollbackFailingInstaller()
+ fake.installed.add(("steps", "my-step"))
+ stack = SimpleNamespace(resolve=lambda target: SimpleNamespace(install_allowed=True))
+ monkeypatch.setattr(command_update, "_build_stack", lambda *a, **kw: stack)
+ monkeypatch.setattr(command_update, "_download_manifest", lambda *a, **kw: manifest)
+ monkeypatch.setattr(adapters, "DefaultPrimitiveInstaller", lambda **kw: fake)
+
+ result = runner.invoke(app, ["bundle", "update", manifest.bundle.id])
+
+ assert result.exit_code == 1, result.output
+ assert fake.refresh_calls == [("steps", "my-step")]
+ output = " ".join(strip_ansi(result.stderr).split())
+ assert "Error: Failed to install step 'my-step'." in output
+ assert "Could not restore step 'my-step'" in output
+ assert "/tmp/speckit-step-refresh-x" in output
+ assert "restore copy failed" in output
+ assert output.index("Failed to install step") < output.index("Could not restore")
diff --git a/tests/specify_cli/bundles/test_primitives.py b/tests/specify_cli/bundles/test_primitives.py
index d92d9a0f9..dfb0788a2 100644
--- a/tests/specify_cli/bundles/test_primitives.py
+++ b/tests/specify_cli/bundles/test_primitives.py
@@ -1051,6 +1051,7 @@ def test_step_refresh_restores_registry_entry_when_reinstall_fails(
seeded = StepRegistry(tmp_path).get("my-step")
assert StepRegistry(tmp_path).is_installed("my-step")
+ package_text = (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8")
# Removal succeeds (real code path); only the re-install fails, which is
# what a catalog 404 / size-limit / type_key mismatch produces.
@@ -1068,10 +1069,55 @@ def test_step_refresh_restores_registry_entry_when_reinstall_fails(
})
monkeypatch.setattr(command_add, "_install_preselected_step", _boom)
+ # The backup copy and the locked remove must both run while the step lock
+ # is held. A nested ``workflow_step_remove`` would take the same flock and
+ # hang, so the stand-in refuses a second hold before calling the real lock.
+ import contextlib
+ import shutil
+
+ import specify_cli.workflows.step.command_remove as command_remove
+ import specify_cli.workflows.step.installer as step_installer
+
+ hold = {"depth": 0}
+ backup_copy_depths: list[int] = []
+ remove_depths: list[int] = []
+ real_txn = step_installer._step_install_transaction
+ real_copytree = shutil.copytree
+ real_remove = command_remove._remove_step_locked
+
+ @contextlib.contextmanager
+ def _tracking_transaction(project_root):
+ if hold["depth"] >= 1:
+ raise AssertionError("nested _step_install_transaction")
+ hold["depth"] += 1
+ try:
+ with real_txn(project_root):
+ yield
+ finally:
+ hold["depth"] -= 1
+
+ def _tracking_copytree(src, dst, *args, **kwargs):
+ if "speckit-step-refresh-" in str(dst):
+ backup_copy_depths.append(hold["depth"])
+ return real_copytree(src, dst, *args, **kwargs)
+
+ def _tracking_remove(project_root, step_id):
+ remove_depths.append(hold["depth"])
+ return real_remove(project_root, step_id)
+
+ monkeypatch.setattr(
+ step_installer, "_step_install_transaction", _tracking_transaction
+ )
+ monkeypatch.setattr(shutil, "copytree", _tracking_copytree)
+ monkeypatch.setattr(command_remove, "_remove_step_locked", _tracking_remove)
+
manager = primitive_manager("steps", tmp_path, allow_network=True)
with pytest.raises(BundlerError):
manager.refresh(_component("steps", "my-step"))
+ assert backup_copy_depths and min(backup_copy_depths) >= 1
+ assert remove_depths and min(remove_depths) >= 1
+
# Read the registry fresh from disk β€” the point of the fix.
restored = StepRegistry(tmp_path)
assert restored.is_installed("my-step"), (
@@ -1080,6 +1126,965 @@ def test_step_refresh_restores_registry_entry_when_reinstall_fails(
# A rollback must be a rollback: the entry comes back byte-for-byte, not
# re-registered with fresh ``installed_at`` / ``updated_at`` stamps.
assert restored.get("my-step") == seeded
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == (
+ package_text
+ )
+ assert (steps_dir / "my-step" / "__init__.py").read_text(encoding="utf-8") == ""
+
+
+def _stub_step_reinstall(monkeypatch, install) -> None:
+ """Give refresh a winning catalog entry and stub the preselected installer."""
+ from specify_cli.workflows.step import command_add
+
+ _patch_winning_entry(monkeypatch, {
+ "_catalog_name": "trusted", "_install_allowed": True,
+ })
+ monkeypatch.setattr(command_add, "_install_preselected_step", install)
+
+
+def test_step_refresh_restores_null_registry_entry_when_reinstall_fails(
+ tmp_path: Path, monkeypatch
+):
+ """A JSON null registry value is installed by key, and rollback restores it.
+
+ ``get()`` returns None for both a missing id and a registered null, so
+ presence must be decided by key membership. The snapshot is tracked
+ separately from its value so rollback can write null back verbatim
+ instead of skipping restore or taking the non-force install path.
+ """
+ import json
+
+ from specify_cli.workflows.catalog import StepRegistry
+
+ steps_dir = tmp_path / ".specify" / "workflows" / "steps"
+ (steps_dir / "my-step").mkdir(parents=True)
+ (steps_dir / "my-step" / "step.yml").write_text(
+ "step:\n type_key: my-step\n", encoding="utf-8"
+ )
+ (steps_dir / "my-step" / "__init__.py").write_text("", encoding="utf-8")
+ (steps_dir / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps({"schema_version": "1.0", "steps": {"my-step": None}}),
+ encoding="utf-8",
+ )
+
+ seeded = StepRegistry(tmp_path)
+ assert seeded.is_installed("my-step")
+ assert seeded.get("my-step") is None
+ package_text = (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8")
+
+ def _boom(step_id, *args, **kwargs):
+ # Refresh must snapshot/remove before reinstall. Delegating to the
+ # non-force install path would still see this id as installed.
+ assert not StepRegistry(tmp_path).is_installed(step_id)
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError, match="Failed to install step 'my-step'"):
+ manager.refresh(_component("steps", "my-step"))
+
+ restored = StepRegistry(tmp_path)
+ assert restored.is_installed("my-step")
+ assert restored.get("my-step") is None
+ saved = json.loads(
+ (steps_dir / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8")
+ )
+ assert "my-step" in saved["steps"]
+ assert saved["steps"]["my-step"] is None
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == (
+ package_text
+ )
+
+
+def test_step_refresh_restores_null_entry_when_removal_fails(
+ tmp_path: Path, monkeypatch
+):
+ """A removal ``BundlerError`` restores the snapshot instead of deleting it.
+
+ ``_remove_step_locked`` drops the registry key before ``rmtree``. A JSON
+ null value cannot be put back by that function, and the removal error used
+ to escape before rollback, so ``finally`` deleted the only copy of the
+ entry and the package.
+ """
+ import json
+ import shutil
+
+ import specify_cli
+ from specify_cli.workflows.catalog import StepRegistry
+
+ steps_dir = tmp_path / ".specify" / "workflows" / "steps"
+ (steps_dir / "my-step").mkdir(parents=True)
+ (steps_dir / "my-step" / "step.yml").write_text(
+ "step:\n type_key: my-step\n", encoding="utf-8"
+ )
+ (steps_dir / "my-step" / "__init__.py").write_text("", encoding="utf-8")
+ (steps_dir / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps({"schema_version": "1.0", "steps": {"my-step": None}}),
+ encoding="utf-8",
+ )
+ package_text = (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8")
+
+ def _add(*_args, **_kwargs):
+ raise AssertionError("reinstall ran after a failed removal")
+
+ monkeypatch.setattr(specify_cli, "workflow_step_add", _add)
+
+ real_rmtree = shutil.rmtree
+ failed = {"done": False}
+
+ def _failing_rmtree(path, *args, **kwargs):
+ target = Path(path)
+ if (
+ not failed["done"]
+ and target.name == "my-step"
+ and "speckit-step-refresh-" not in str(target)
+ ):
+ # Directory is gone, then removal reports failure. The null key
+ # was already deleted and cannot be restored by ``_remove_step_locked``.
+ failed["done"] = True
+ real_rmtree(path, *args, **kwargs)
+ raise OSError("simulated rmtree failure")
+ return real_rmtree(path, *args, **kwargs)
+
+ monkeypatch.setattr(shutil, "rmtree", _failing_rmtree)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError, match="Failed to remove step 'my-step'") as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert failed["done"]
+ assert not getattr(caught.value, "__notes__", ())
+ restored = StepRegistry(tmp_path)
+ assert restored.is_installed("my-step")
+ assert restored.get("my-step") is None
+ saved = json.loads(
+ (steps_dir / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8")
+ )
+ assert saved["steps"]["my-step"] is None
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == (
+ package_text
+ )
+ assert (steps_dir / "my-step" / "__init__.py").read_text(encoding="utf-8") == ""
+
+
+def _seed_refresh_step(root: Path) -> tuple[Path, dict]:
+ """Install ``my-step`` on disk the way a previous ``step add`` would have."""
+ import json
+
+ from specify_cli.workflows.catalog import StepRegistry
+
+ steps_dir = root / ".specify" / "workflows" / "steps"
+ package = steps_dir / "my-step"
+ package.mkdir(parents=True)
+ (package / "step.yml").write_text(
+ "step:\n type_key: my-step\n", encoding="utf-8"
+ )
+ (package / "__init__.py").write_text("", encoding="utf-8")
+ entry = {
+ "name": "My Step",
+ "version": "1.0.0",
+ "type_key": "my-step",
+ "installed_at": "2020-01-01T00:00:00+00:00",
+ "updated_at": "2020-02-02T00:00:00+00:00",
+ }
+ (steps_dir / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps(
+ {"schema_version": "1.0", "steps": {"my-step": entry}}
+ ),
+ encoding="utf-8",
+ )
+ return steps_dir, entry
+
+
+def test_step_refresh_keeps_a_later_commit_when_reinstall_fails(
+ tmp_path: Path, monkeypatch
+):
+ """A step operation that lands before rollback must survive the failure.
+
+ The pre-fix restore copied the backup with ``dirs_exist_ok=True``, which
+ overwrote a package a later ``step add`` had already committed.
+ """
+ import json
+
+ from specify_cli.workflows.catalog import StepRegistry
+
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ newer_step_yml = "step:\n type_key: my-step\n version: 2.0.0\n"
+ committed = {
+ "my-step": {
+ "name": "My Step",
+ "version": "2.0.0",
+ "type_key": "my-step",
+ "installed_at": "2024-03-03T00:00:00+00:00",
+ "updated_at": "2024-04-04T00:00:00+00:00",
+ },
+ "other-step": {
+ "name": "Other Step",
+ "version": "1.0.0",
+ "installed_at": "2024-05-05T00:00:00+00:00",
+ "updated_at": "2024-05-05T00:00:00+00:00",
+ },
+ }
+
+ def _boom(step_id, *args, **kwargs):
+ package = steps_dir / step_id
+ package.mkdir(parents=True, exist_ok=True)
+ (package / "step.yml").write_text(newer_step_yml, encoding="utf-8")
+ (steps_dir / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps({"schema_version": "1.0", "steps": committed}),
+ encoding="utf-8",
+ )
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError, match="Failed to install step 'my-step'"):
+ manager.refresh(_component("steps", "my-step"))
+
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == (
+ newer_step_yml
+ )
+ assert StepRegistry(tmp_path).data["steps"] == committed
+
+
+def test_step_refresh_rollback_keeps_case_variant_commit(
+ tmp_path: Path, monkeypatch
+):
+ """Rollback must not delete or collide with a case-variant committed first."""
+ import json
+ import shutil
+
+ from specify_cli.workflows.catalog import StepRegistry
+
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ variant, newer = "MY-STEP", "step:\n type_key: MY-STEP\n"
+ committed = {variant: {"name": "My Step", "version": "2.0.0", "type_key": variant}}
+
+ def _boom(step_id, *_args, **_kwargs):
+ (steps_dir / variant).mkdir()
+ (steps_dir / variant / "step.yml").write_text(newer, encoding="utf-8")
+ (steps_dir / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps({"schema_version": "1.0", "steps": committed}),
+ encoding="utf-8",
+ )
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+ with pytest.raises(BundlerError) as caught:
+ primitive_manager("steps", tmp_path, allow_network=True).refresh(
+ _component("steps", "my-step")
+ )
+
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ note = caught.value.__notes__[0]
+ assert "case-insensitively" in note
+ assert (steps_dir / variant / "step.yml").read_text(encoding="utf-8") == newer
+ assert {path.name for path in steps_dir.iterdir() if path.is_dir()} == {variant}
+ saved = json.loads(
+ (steps_dir / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8")
+ )
+ assert saved["steps"] == committed
+ backup_root = _backup_root_from_note(note)
+ try:
+ assert (backup_root / "my-step" / "step.yml").is_file()
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
+
+
+def test_step_refresh_rollback_keeps_registry_keys_written_after_load(
+ tmp_path: Path, monkeypatch
+):
+ """A competing install waits on rollback's lock; both entries survive.
+
+ Rollback is paused after its final registry read. An installer that takes
+ the shared step lock must block until rollback saves, or its new key is
+ overwritten by that stale document.
+ """
+ import json
+ import threading
+
+ from specify_cli.workflows.step import installer as step_installer
+ from tests.lock_helpers import wait_until_blocked_or_done, watch_lock_attempt
+
+ steps_dir, entry = _seed_refresh_step(tmp_path)
+ other_pkg = tmp_path / "pkg-other"
+ other_pkg.mkdir()
+ (other_pkg / "step.yml").write_text(
+ "step:\n type_key: other-step\n name: Other\n version: 1.0.0\n",
+ encoding="utf-8",
+ )
+ (other_pkg / "__init__.py").write_text("# init\n", encoding="utf-8")
+ real_load = StepRegistry._load
+ state = {"n": 0}
+ loaded, release = threading.Event(), threading.Event()
+
+ def _load(self):
+ data = real_load(self)
+ steps = data.get("steps") if isinstance(data, dict) else None
+ if (
+ threading.current_thread().name == "refresh"
+ and isinstance(steps, dict)
+ and "my-step" not in steps
+ ):
+ state["n"] += 1
+ if state["n"] == 2:
+ loaded.set()
+ assert release.wait(10), "rollback was never released"
+ return data
+
+ def _boom(*_args, **_kwargs):
+ raise BundlerError("Failed to install step 'my-step'.")
+
+ monkeypatch.setattr(StepRegistry, "_load", _load)
+ _stub_step_reinstall(monkeypatch, _boom)
+ attempted = watch_lock_attempt(monkeypatch, "installer")
+ errors: dict[str, BaseException] = {}
+ refresh_done, install_done = threading.Event(), threading.Event()
+
+ def _target(name, fn, done):
+ try:
+ fn()
+ except BaseException as exc: # noqa: BLE001
+ errors[name] = exc
+ finally:
+ done.set()
+
+ def _refresh():
+ primitive_manager("steps", tmp_path, allow_network=True).refresh(
+ _component("steps", "my-step")
+ )
+
+ refresh = threading.Thread(
+ target=_target, name="refresh", args=("refresh", _refresh, refresh_done),
+ daemon=True,
+ )
+ installer = threading.Thread(
+ target=_target,
+ name="installer",
+ args=(
+ "installer",
+ lambda: step_installer.install_step_package(
+ tmp_path, "other-step", other_pkg, source="local"
+ ),
+ install_done,
+ ),
+ daemon=True,
+ )
+ refresh.start()
+ try:
+ assert loaded.wait(10), "rollback never paused after its final registry read"
+ installer.start()
+ wait_until_blocked_or_done(attempted, install_done)
+ assert attempted.is_set()
+ assert not install_done.wait(0.2)
+ finally:
+ release.set()
+ refresh.join(10)
+ if installer.ident is not None:
+ installer.join(10)
+ assert not refresh.is_alive()
+ assert not installer.is_alive()
+ assert isinstance(errors.get("refresh"), BundlerError)
+ assert str(errors["refresh"]) == "Failed to install step 'my-step'."
+ assert errors.get("installer") is None, errors.get("installer")
+ saved = json.loads(
+ (steps_dir / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8")
+ )
+ assert saved["steps"]["my-step"] == entry
+ assert "other-step" in saved["steps"]
+ assert (steps_dir / "my-step").is_dir()
+ assert (steps_dir / "other-step").is_dir()
+
+
[email protected]("failure", ["copy", "save"])
+def test_step_refresh_notes_restoration_failure_and_keeps_backup(
+ tmp_path: Path, monkeypatch, failure: str
+):
+ """A failed copy-back or registry write stays on the original install error.
+
+ A chained installer or catalog cause stays on that error too.
+ """
+ import shutil
+
+ from specify_cli.workflows.catalog import StepRegistry, StepValidationError
+
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ original_step_yml = (steps_dir / "my-step" / "step.yml").read_text(
+ encoding="utf-8"
+ )
+ cause = RuntimeError("catalog lookup failed")
+
+ def _boom(step_id, *args, **kwargs):
+ raise BundlerError(f"Failed to install step '{step_id}'.") from cause
+
+ if failure == "copy":
+ real_copytree = shutil.copytree
+
+ def _copytree(src, dst, *args, **kwargs):
+ if "speckit-step-refresh-" in str(src):
+ raise OSError("restore copy failed")
+ return real_copytree(src, dst, *args, **kwargs)
+
+ monkeypatch.setattr(shutil, "copytree", _copytree)
+ _stub_step_reinstall(monkeypatch, _boom)
+ failure_text = "restore copy failed"
+ else:
+ real_save = StepRegistry.save
+ armed = {"on": False}
+
+ def _boom_then_arm(step_id, *args, **kwargs):
+ armed["on"] = True
+ raise BundlerError(f"Failed to install step '{step_id}'.") from cause
+
+ def _save(self):
+ if armed["on"]:
+ raise StepValidationError("registry write failed")
+ return real_save(self)
+
+ _stub_step_reinstall(monkeypatch, _boom_then_arm)
+ monkeypatch.setattr(StepRegistry, "save", _save)
+ failure_text = "registry write failed"
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError) as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ assert caught.value.__cause__ is cause
+ note = caught.value.__notes__[0]
+ assert failure_text in note
+ assert "speckit-step-refresh-" in note
+ backup_root = Path(note.split("from backup '", 1)[1].split("'", 1)[0])
+ try:
+ assert backup_root.is_dir()
+ assert (backup_root / "my-step" / "step.yml").read_text(
+ encoding="utf-8"
+ ) == original_step_yml
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
+
+
+def test_step_refresh_skips_backup_when_offline_or_not_installed(
+ tmp_path: Path, monkeypatch
+):
+ """Offline refresh, and a step absent under the lock, do not back up.
+
+ Online refresh still takes the install lock to read the registry. Only
+ the offline gate may skip that lock; a missing locked snapshot delegates
+ to install with no backup.
+ """
+ import tempfile
+
+ import specify_cli.workflows.step.installer as step_installer
+
+ calls: list[tuple[str, Path]] = []
+
+ def _add(step_id: str, **_kwargs) -> None:
+ calls.append((step_id, Path.cwd()))
+
+ def _forbid_step_lock(*_args, **_kwargs):
+ raise AssertionError("offline step refresh took the step lock")
+
+ real_mkdtemp = tempfile.mkdtemp
+
+ def _mkdtemp(*args, **kwargs):
+ prefix = kwargs.get("prefix", args[0] if args else "")
+ if str(prefix).startswith("speckit-step-refresh-"):
+ raise AssertionError("step refresh took the backup path")
+ return real_mkdtemp(*args, **kwargs)
+
+ _stub_step_reinstall(monkeypatch, _add)
+ monkeypatch.setattr(tempfile, "mkdtemp", _mkdtemp)
+
+ missing = primitive_manager("steps", tmp_path, allow_network=True)
+ missing.refresh(_component("steps", "missing-step"))
+ assert calls == [("missing-step", tmp_path)]
+
+ monkeypatch.setattr(step_installer, "_step_install_transaction", _forbid_step_lock)
+ _seed_refresh_step(tmp_path)
+ offline = primitive_manager("steps", tmp_path, allow_network=False)
+ with pytest.raises(
+ BundlerError, match="refreshing this component requires network access"
+ ):
+ offline.refresh(_component("steps", "my-step"))
+ assert calls == [("missing-step", tmp_path)]
+
+
+def test_step_refresh_installs_when_removed_before_locked_snapshot(
+ tmp_path: Path, monkeypatch
+):
+ """A remove that commits before the locked snapshot takes the install path.
+
+ The manager is built while the step is installed, so the pre-lock
+ ``is_installed`` check stays True. A concurrent ``step remove`` then
+ deletes the registry entry and package before this refresh enters its
+ lock. The locked snapshot is absent, so refresh must release the lock
+ and delegate to ``install`` without ``_remove_step_locked`` or a backup.
+ """
+ import contextlib
+ import json
+ import shutil
+ import tempfile
+
+ import specify_cli.workflows.step.command_remove as command_remove
+ import specify_cli.workflows.step.installer as step_installer
+
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ registry_path = steps_dir / StepRegistry.REGISTRY_FILE
+ component = _component("steps", "my-step")
+
+ hold = {"depth": 0}
+ removed = {"done": False}
+ remove_calls: list[str] = []
+ install_calls: list[tuple[str, int]] = []
+ backup_dirs: list[Path] = []
+ real_txn = step_installer._step_install_transaction
+ real_remove = command_remove._remove_step_locked
+ real_mkdtemp = tempfile.mkdtemp
+
+ def _commit_remove() -> None:
+ document = json.loads(registry_path.read_text(encoding="utf-8"))
+ document["steps"].pop("my-step", None)
+ registry_path.write_text(json.dumps(document), encoding="utf-8")
+ shutil.rmtree(steps_dir / "my-step")
+ assert not StepRegistry(tmp_path).is_installed("my-step")
+ assert not (steps_dir / "my-step").exists()
+
+ @contextlib.contextmanager
+ def _remove_before_first_lock(project_root):
+ # Concurrent ``step remove`` commits after manager construction and
+ # before this transaction's locked snapshot.
+ if not removed["done"]:
+ removed["done"] = True
+ _commit_remove()
+ if hold["depth"] >= 1:
+ raise AssertionError("nested _step_install_transaction")
+ hold["depth"] += 1
+ try:
+ with real_txn(project_root):
+ yield
+ finally:
+ hold["depth"] -= 1
+
+ def _tracking_remove(project_root, step_id):
+ remove_calls.append(step_id)
+ return real_remove(project_root, step_id)
+
+ def _add(step_id: str, *args, **kwargs) -> None:
+ install_calls.append((step_id, hold["depth"]))
+
+ def _mkdtemp(*args, **kwargs):
+ prefix = kwargs.get("prefix", args[0] if args else "")
+ path = Path(real_mkdtemp(*args, **kwargs))
+ if str(prefix).startswith("speckit-step-refresh-"):
+ backup_dirs.append(path)
+ return str(path)
+
+ monkeypatch.setattr(
+ step_installer, "_step_install_transaction", _remove_before_first_lock
+ )
+ monkeypatch.setattr(command_remove, "_remove_step_locked", _tracking_remove)
+ _stub_step_reinstall(monkeypatch, _add)
+ monkeypatch.setattr(tempfile, "mkdtemp", _mkdtemp)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ assert manager.is_installed(component)
+
+ manager.refresh(component)
+
+ assert removed["done"]
+ assert remove_calls == []
+ assert install_calls == [("my-step", 0)]
+ # No refresh backup is created, so none can be left behind.
+ assert backup_dirs == []
+
+
+def test_step_refresh_snapshots_step_added_after_manager_construction(
+ tmp_path: Path, monkeypatch
+):
+ """Online refresh reads presence under the lock, not the constructor registry.
+
+ The manager is built while the step is absent, so ``self._registry`` would
+ skip straight to non-force ``install``. A concurrent ``step add`` then
+ commits. Refresh must snapshot, remove, and reinstall; ``check_installable``
+ would reject the step if removal had not happened first.
+ """
+ import contextlib
+ import tempfile
+
+ import specify_cli.workflows.step.command_remove as command_remove
+ import specify_cli.workflows.step.installer as step_installer
+ import typer
+
+ component = _component("steps", "my-step")
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ assert not manager.is_installed(component)
+
+ _seed_refresh_step(tmp_path)
+ assert StepRegistry(tmp_path).is_installed("my-step")
+ assert not manager.is_installed(component)
+
+ hold = {"depth": 0}
+ remove_depths: list[int] = []
+ install_calls: list[tuple[str, int]] = []
+ backup_dirs: list[Path] = []
+ real_txn = step_installer._step_install_transaction
+ real_remove = command_remove._remove_step_locked
+ real_mkdtemp = tempfile.mkdtemp
+
+ @contextlib.contextmanager
+ def _tracking_transaction(project_root):
+ if hold["depth"] >= 1:
+ raise AssertionError("nested _step_install_transaction")
+ hold["depth"] += 1
+ try:
+ with real_txn(project_root):
+ yield
+ finally:
+ hold["depth"] -= 1
+
+ def _tracking_remove(project_root, step_id):
+ remove_depths.append(hold["depth"])
+ assert backup_dirs
+ assert (backup_dirs[-1] / step_id / "step.yml").is_file()
+ return real_remove(project_root, step_id)
+
+ def _add(step_id: str, *args, **kwargs) -> None:
+ try:
+ step_installer.check_installable(tmp_path, step_id, force=False)
+ except step_installer.StepInstallError as exc:
+ raise typer.Exit(1) from exc
+ install_calls.append((step_id, hold["depth"]))
+
+ def _mkdtemp(*args, **kwargs):
+ prefix = kwargs.get("prefix", args[0] if args else "")
+ path = Path(real_mkdtemp(*args, **kwargs))
+ if str(prefix).startswith("speckit-step-refresh-"):
+ backup_dirs.append(path)
+ return str(path)
+
+ monkeypatch.setattr(
+ step_installer, "_step_install_transaction", _tracking_transaction
+ )
+ monkeypatch.setattr(command_remove, "_remove_step_locked", _tracking_remove)
+ _stub_step_reinstall(monkeypatch, _add)
+ monkeypatch.setattr(tempfile, "mkdtemp", _mkdtemp)
+
+ manager.refresh(component)
+
+ assert remove_depths == [1]
+ assert install_calls == [("my-step", 0)]
+ assert backup_dirs
+ assert all(not path.exists() for path in backup_dirs)
+
+
+def test_step_refresh_reinstalls_relative_project_root(tmp_path: Path, monkeypatch):
+ """A relative root is removed in place and refresh still reaches reinstall.
+
+ ``_chdir(Path("project"))`` before ``_remove_step_locked`` resolves that
+ same root a second time, so removal reports the step as not installed.
+ """
+ import specify_cli.workflows.step.command_remove as command_remove
+
+ project = tmp_path / "project"
+ project.mkdir()
+ _seed_refresh_step(project)
+ monkeypatch.chdir(tmp_path)
+ outside = Path.cwd()
+ relative = Path("project")
+ seen: dict = {}
+ real_remove = command_remove._remove_step_locked
+
+ def _tracking_remove(project_root, step_id):
+ seen["cwd"] = Path.cwd()
+ seen["root"] = Path(project_root)
+ return real_remove(project_root, step_id)
+
+ def _add(step_id, *_args, **_kwargs):
+ seen["installed"] = step_id
+
+ monkeypatch.setattr(command_remove, "_remove_step_locked", _tracking_remove)
+ _stub_step_reinstall(monkeypatch, _add)
+ primitive_manager("steps", relative, allow_network=True).refresh(
+ _component("steps", "my-step")
+ )
+
+ assert seen == {"cwd": outside, "root": relative, "installed": "my-step"}
+ assert not (project / ".specify" / "workflows" / "steps" / "my-step").exists()
+ assert not (project / "project").exists()
+ assert not StepRegistry(project).is_installed("my-step")
+
+
+def _backup_root_from_note(note: str) -> Path:
+ return Path(note.split("from backup '", 1)[1].split("'", 1)[0])
+
+
+def test_step_refresh_wraps_initial_lock_failure_without_backup(
+ tmp_path: Path, monkeypatch
+):
+ """Lock failure before the snapshot is wrapped and creates no backup."""
+ import tempfile
+
+ import specify_cli
+ import specify_cli.workflows.step.installer as step_installer
+
+ steps_dir, entry = _seed_refresh_step(tmp_path)
+ package_text = (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8")
+ registry_text = (steps_dir / StepRegistry.REGISTRY_FILE).read_text(
+ encoding="utf-8"
+ )
+
+ def _lock_fails(*_args, **_kwargs):
+ raise step_installer.StepInstallError(
+ "Failed to acquire the step lock: busy"
+ )
+
+ def _add(*_args, **_kwargs):
+ raise AssertionError("install ran after the initial lock failure")
+
+ created: list[str] = []
+ real_mkdtemp = tempfile.mkdtemp
+
+ def _mkdtemp(*args, **kwargs):
+ prefix = kwargs.get("prefix", args[0] if args else "")
+ created.append(str(prefix))
+ return real_mkdtemp(*args, **kwargs)
+
+ monkeypatch.setattr(step_installer, "_step_install_transaction", _lock_fails)
+ monkeypatch.setattr(specify_cli, "workflow_step_add", _add)
+ monkeypatch.setattr(tempfile, "mkdtemp", _mkdtemp)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError) as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert str(caught.value) == (
+ "Failed to refresh step 'my-step': Failed to acquire the step lock: busy"
+ )
+ assert isinstance(caught.value.__cause__, step_installer.StepInstallError)
+ assert not any(prefix.startswith("speckit-step-refresh-") for prefix in created)
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == (
+ package_text
+ )
+ assert (steps_dir / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8") == (
+ registry_text
+ )
+ assert StepRegistry(tmp_path).get("my-step") == entry
+
+
+def test_step_refresh_notes_rollback_lock_failure_and_keeps_backup(
+ tmp_path: Path, monkeypatch
+):
+ """A failed rollback lock keeps the install error, a note, and the backup."""
+ import contextlib
+ import shutil
+
+ import specify_cli.workflows.step.installer as step_installer
+
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ original_step_yml = (steps_dir / "my-step" / "step.yml").read_text(
+ encoding="utf-8"
+ )
+
+ def _boom(step_id, *args, **kwargs):
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+
+ real_txn = step_installer._step_install_transaction
+ calls = {"n": 0}
+
+ @contextlib.contextmanager
+ def _fail_second(project_root):
+ calls["n"] += 1
+ if calls["n"] >= 2:
+ raise step_installer.StepInstallError(
+ "Failed to acquire the step lock: busy"
+ )
+ with real_txn(project_root):
+ yield
+
+ monkeypatch.setattr(step_installer, "_step_install_transaction", _fail_second)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError) as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert calls["n"] == 2
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ assert caught.value.__cause__ is None
+ note = caught.value.__notes__[0]
+ assert "Failed to acquire the step lock: busy" in note
+ assert "Could not restore step 'my-step'" in note
+ backup_root = _backup_root_from_note(note)
+ try:
+ assert backup_root.is_dir()
+ assert (backup_root / "my-step" / "step.yml").read_text(
+ encoding="utf-8"
+ ) == original_step_yml
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
+ assert not (steps_dir / "my-step").exists()
+ assert not StepRegistry(tmp_path).is_installed("my-step")
+
+
+def _require_directory_symlink(tmp_path: Path) -> None:
+ probe_target = tmp_path / "symlink-probe-target"
+ probe_target.mkdir()
+ probe = tmp_path / "symlink-probe"
+ try:
+ probe.symlink_to(probe_target, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"cannot create symlink: {exc}")
+
+
+def test_step_refresh_rollback_refuses_swapped_steps_symlink(
+ tmp_path: Path, monkeypatch
+):
+ """Rollback must not read or delete through a steps directory symlink."""
+ import json
+ import shutil
+
+ _require_directory_symlink(tmp_path)
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ outside = tmp_path / "outside"
+ external_step = outside / "my-step"
+ external_step.mkdir(parents=True)
+ (external_step / "secret.txt").write_text("do-not-delete", encoding="utf-8")
+ external_registry = {
+ "schema_version": "1.0",
+ "steps": {"other-step": {"name": "Other", "version": "9.9.9"}},
+ }
+ (outside / StepRegistry.REGISTRY_FILE).write_text(
+ json.dumps(external_registry), encoding="utf-8"
+ )
+
+ def _boom(step_id, *args, **kwargs):
+ # Reinstall is outside the lock: swap the steps directory for an
+ # external tree before rollback reacquires it.
+ shutil.rmtree(steps_dir)
+ steps_dir.symlink_to(outside, target_is_directory=True)
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError) as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ note = caught.value.__notes__[0]
+ assert "Refusing to use symlinked step directory" in note
+ assert (external_step / "secret.txt").read_text(encoding="utf-8") == (
+ "do-not-delete"
+ )
+ assert not (external_step / "step.yml").exists()
+ assert (
+ json.loads((outside / StepRegistry.REGISTRY_FILE).read_text(encoding="utf-8"))
+ == external_registry
+ )
+ assert steps_dir.is_symlink()
+ backup_root = _backup_root_from_note(note)
+ try:
+ assert (backup_root / "my-step" / "step.yml").is_file()
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
+
+
+def test_step_refresh_rollback_refuses_symlinked_step_directory(
+ tmp_path: Path, monkeypatch
+):
+ """Rollback must not delete a step directory that is itself a symlink."""
+ import shutil
+
+ _require_directory_symlink(tmp_path)
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ external_step = tmp_path / "outside-step"
+ external_step.mkdir()
+ (external_step / "secret.txt").write_text("do-not-delete", encoding="utf-8")
+
+ def _boom(step_id, *args, **kwargs):
+ link = steps_dir / step_id
+ link.symlink_to(external_step, target_is_directory=True)
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+
+ manager = primitive_manager("steps", tmp_path, allow_network=True)
+ with pytest.raises(BundlerError) as caught:
+ manager.refresh(_component("steps", "my-step"))
+
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ note = caught.value.__notes__[0]
+ assert "Refusing to install step through a symlinked path" in note
+ assert (external_step / "secret.txt").read_text(encoding="utf-8") == (
+ "do-not-delete"
+ )
+ assert (steps_dir / "my-step").is_symlink()
+ backup_root = _backup_root_from_note(note)
+ try:
+ assert (backup_root / "my-step" / "step.yml").is_file()
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
+
+
+def test_step_refresh_rollback_refuses_symlinked_registry(
+ tmp_path: Path, monkeypatch
+):
+ """Rollback must not replace a package when step-registry.json is a symlink.
+
+ ``StepRegistry._load`` returns an empty registry for that link and does
+ not raise, so the step looks absent. The newer package and the link
+ target stay untouched, and the backup is kept.
+ """
+ import shutil
+
+ _require_directory_symlink(tmp_path)
+ steps_dir, _entry = _seed_refresh_step(tmp_path)
+ newer = "step:\n type_key: my-step\n version: 2.0.0\n"
+ registry_path = steps_dir / StepRegistry.REGISTRY_FILE
+ registry_target = tmp_path / "linked-step-registry.json"
+ linked_text = (
+ '{"schema_version":"1.0","steps":{"my-step":'
+ '{"sentinel":"linked-registry"}}}\n'
+ )
+ registry_target.write_text(linked_text, encoding="utf-8")
+
+ def _boom(step_id, *_args, **_kwargs):
+ package = steps_dir / step_id
+ package.mkdir()
+ (package / "step.yml").write_text(newer, encoding="utf-8")
+ (package / "__init__.py").write_text("# newer\n", encoding="utf-8")
+ registry_path.unlink()
+ registry_path.symlink_to(registry_target)
+ raise BundlerError(f"Failed to install step '{step_id}'.")
+
+ _stub_step_reinstall(monkeypatch, _boom)
+ with pytest.raises(BundlerError) as caught:
+ primitive_manager("steps", tmp_path, allow_network=True).refresh(
+ _component("steps", "my-step")
+ )
+
+ assert str(caught.value) == "Failed to install step 'my-step'."
+ note = caught.value.__notes__[0]
+ assert "Refusing to restore" in note
+ assert "symlinked step registry" in note
+ assert registry_path.is_symlink()
+ assert registry_path.resolve() == registry_target.resolve()
+ assert registry_target.read_text(encoding="utf-8") == linked_text
+ assert (steps_dir / "my-step" / "step.yml").read_text(encoding="utf-8") == newer
+ assert (steps_dir / "my-step" / "__init__.py").read_text(encoding="utf-8") == (
+ "# newer\n"
+ )
+ backup_root = _backup_root_from_note(note)
+ try:
+ assert (backup_root / "my-step" / "step.yml").read_text(
+ encoding="utf-8"
+ ) == "step:\n type_key: my-step\n"
+ finally:
+ shutil.rmtree(backup_root, ignore_errors=True)
_HISTORICAL_SHA = "a" * 64