π« 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.pyindex 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.pyindex 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.pyindex 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 consolefrom . import BundlerErrorfrom ._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)returndiff --git a/src/specify_cli/bundles/primitives.py b/src/specify_cli/bundles/primitives.pyindex 51206a853..f91059225 100644--- a/src/specify_cli/bundles/primitives.py+++ b/src/specify_cli/bundles/primitives.py@@ -641,55 +641,154 @@ class _StepKindManager:) from excdef 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 copyimport shutilimport 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 = Nonetry:- 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__``.raisefinally:- 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_removediff --git a/tests/specify_cli/bundles/test_commands.py b/tests/specify_cli/bundles/test_commands.pyindex 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.pyindex 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