Skip to content

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

84.9 KB
Raw Blame
"""Unit tests for the primitive-dispatch bridge (T044).

Covers routing, offline gating, and the network-aware ``DefaultPrimitiveInstaller``
seam β€” without touching real catalogs or the network (Constitution Principle II,
offline-first).
"""
from __future__ import annotations

from pathlib import Path
from types import SimpleNamespace

import pytest

from specify_cli.bundler import BundlerError
from specify_cli.bundles import component_catalog
from specify_cli.bundles.adapters import DefaultPrimitiveInstaller
from specify_cli.bundles.manifest import ComponentRef
from specify_cli.bundles.primitives import (
    _ExtensionKindManager,
    _PresetKindManager,
    _StepKindManager,
    _WorkflowKindManager,
    primitive_manager,
)
from specify_cli.extensions import ExtensionRegistry
from specify_cli.presets import PresetRegistry
from specify_cli.workflows.catalog import StepRegistry, WorkflowRegistry
from tests.specify_cli.bundles.helpers import valid_manifest_dict


def _component(kind: str, cid: str = "x") -> ComponentRef:
    return ComponentRef(kind=kind, id=cid)


def _patch_winning_entry(monkeypatch, entry: dict | None) -> None:
    monkeypatch.setattr(
        component_catalog, "winning_catalog_entry",
        lambda _catalog, _component: entry,
    )


def _patch_catalog_sources(monkeypatch, catalog_type, kind, sources, fetches=None):
    """Keep the bundle resolver real while replacing only network catalog reads."""
    configured = [
        SimpleNamespace(name=name, url=f"https://example.com/{name}.json",
                        install_allowed=True)
        for name, _entries in sources
    ]
    payloads = {
        source.url: {kind: entries}
        for source, (_name, entries) in zip(configured, sources)
    }
    monkeypatch.setattr(catalog_type, "get_active_catalogs", lambda self: configured)

    def fetch(_self, source):
        if fetches is not None:
            fetches.append(source.name)
        return payloads[source.url]

    monkeypatch.setattr(catalog_type, "_fetch_single_catalog", fetch)


def _workflow_or_step_entry(kind: str, cid: str) -> dict:
    old = {"url": "https://example.com/old/step.yml" if kind == "steps"
           else "https://example.com/old/workflow.yml"}
    if kind == "steps":
        old["sha256"] = {"step.yml": "a" * 64, "__init__.py": "b" * 64}
    else:
        old["sha256"] = "a" * 64
    return {
        "id": cid, "version": "2.0.0", "url": "https://example.com/latest",
        "releases": {"1.0.0": old},
    }


def test_primitive_manager_routes_each_kind(tmp_path: Path):
    assert isinstance(primitive_manager("presets", tmp_path), _PresetKindManager)
    assert isinstance(primitive_manager("extensions", tmp_path), _ExtensionKindManager)
    assert isinstance(primitive_manager("workflows", tmp_path), _WorkflowKindManager)
    assert isinstance(primitive_manager("steps", tmp_path), _StepKindManager)


def test_primitive_manager_rejects_unknown_kind(tmp_path: Path):
    with pytest.raises(BundlerError, match="Unknown component kind"):
        primitive_manager("bogus", tmp_path)


def test_offline_preset_not_bundled_refuses(tmp_path: Path):
    manager = primitive_manager("presets", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="network access is disabled"):
        manager.install(_component("presets", "definitely-not-bundled"))


def test_offline_extension_not_bundled_refuses(tmp_path: Path):
    manager = primitive_manager("extensions", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="network access is disabled"):
        manager.install(_component("extensions", "definitely-not-bundled"))


def test_offline_workflow_refuses_without_network(tmp_path: Path):
    manager = primitive_manager("workflows", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="network access is disabled"):
        manager.install(_component("workflows"))


def test_offline_step_refuses_without_network(tmp_path: Path):
    manager = primitive_manager("steps", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="network access is disabled"):
        manager.install(_component("steps"))


def test_step_manager_delegates_catalog_install_from_bundle_root(tmp_path, monkeypatch):
    from specify_cli.workflows.step import command_add

    calls: list[tuple[str, Path]] = []

    def _add(project_root, step_id, **options) -> None:
        calls.append((step_id, Path.cwd()))

    (tmp_path / ".specify").mkdir()
    _patch_winning_entry(monkeypatch, {
        "id": "catalog-step", "_catalog_name": "trusted", "_install_allowed": True,
    })
    monkeypatch.setattr(command_add, "_install_from_catalog", _add)
    manager = _StepKindManager(tmp_path, allow_network=True)

    manager.install(_component("steps", "catalog-step"))

    assert calls == [("catalog-step", tmp_path)]


def test_step_manager_rejects_unsafe_id_before_catalog_lookup(tmp_path, monkeypatch):
    monkeypatch.setattr(
        component_catalog, "winning_catalog_entry",
        lambda *args: pytest.fail("invalid ID reached catalog lookup"),
    )

    with pytest.raises(BundlerError, match="step"):
        primitive_manager("steps", tmp_path).install(
            _component("steps", "../outside"),
        )


@pytest.mark.parametrize(
    "kind,catalog_module,catalog_class",
    [
        ("workflows", "specify_cli.workflows.catalog", "WorkflowCatalog"),
        ("steps", "specify_cli.workflows.catalog", "StepCatalog"),
    ],
)
def test_catalog_workflow_and_step_pins_delegate_exact_release(
    tmp_path, monkeypatch, kind, catalog_module, catalog_class,
):
    import importlib

    import specify_cli._assets as assets
    from specify_cli.workflows import _commands as workflow_cli
    from specify_cli.workflows.step import command_add as step_add

    (tmp_path / ".specify").mkdir()
    if kind == "workflows":
        monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda _id: None)
    catalog = getattr(importlib.import_module(catalog_module), catalog_class)
    fetches = []
    _patch_catalog_sources(
        monkeypatch, catalog, kind,
        [("trusted", {"catalog-id": _workflow_or_step_entry(kind, "catalog-id")})],
        fetches,
    )
    calls = []
    installer = (
        (workflow_cli, "_install_workflow_from_catalog")
        if kind == "workflows"
        else (step_add, "_install_from_catalog")
    )
    monkeypatch.setattr(
        *installer,
        lambda project_root, destination, cid=None, **options: calls.append(
            (cid or destination, options, Path.cwd())
        ),
    )
    component = ComponentRef(kind=kind, id="catalog-id", version="1.0.0", source="trusted")

    primitive_manager(kind, tmp_path).install(component)

    assert fetches == ["trusted"]
    assert calls[0][0] == component.id
    assert calls[0][1][
        "requested_version" if kind == "workflows" else "version"
    ] == "1.0.0"
    assert calls[0][1]["selected_info"]["version"] == "1.0.0"
    assert calls[0][1]["selected_info"]["_catalog_name"] == "trusted"
    assert calls[0][2] == tmp_path


@pytest.mark.parametrize("kind", ["workflows", "steps"])
def test_catalog_component_installs_preselected_release_without_second_lookup(
    tmp_path, monkeypatch, kind,
):
    import specify_cli
    import specify_cli._assets as assets
    from specify_cli.workflows import _commands as workflow_cli
    from specify_cli.workflows.catalog import StepCatalog, WorkflowCatalog
    from specify_cli.workflows.step import command_add as step_add

    catalog = WorkflowCatalog if kind == "workflows" else StepCatalog
    current = _workflow_or_step_entry(kind, "catalog-id")
    fetches = []
    _patch_catalog_sources(
        monkeypatch, catalog, kind, [("trusted", {"catalog-id": current})], fetches,
    )
    (tmp_path / ".specify").mkdir()
    monkeypatch.setattr(
        catalog, "get_workflow_info" if kind == "workflows" else "get_step_info",
        lambda *args, **kwargs: pytest.fail("installer re-resolved the catalog"),
    )

    calls = []
    if kind == "workflows":
        monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda _id: None)
        monkeypatch.setattr(
            workflow_cli, "_install_workflow_from_catalog",
            lambda *args, **kwargs: calls.append(kwargs),
        )
        monkeypatch.setattr(
            specify_cli, "workflow_add",
            lambda *args, **kwargs: pytest.fail("workflow_add re-resolved the catalog"),
        )
    else:
        monkeypatch.setattr(
            step_add, "_install_from_catalog",
            lambda *args, **kwargs: calls.append(kwargs),
        )
        monkeypatch.setattr(
            specify_cli, "workflow_step_add",
            lambda *args, **kwargs: pytest.fail("workflow_step_add re-resolved the catalog"),
        )

    primitive_manager(kind, tmp_path).install(ComponentRef(
        kind=kind, id="catalog-id", version="1.0.0", source="trusted"
    ))

    assert fetches == ["trusted"]
    assert len(calls) == 1
    assert calls[0]["selected_info"] == {
        "id": "catalog-id", "version": "1.0.0",
        **current["releases"]["1.0.0"],
        "_catalog_name": "trusted", "_install_allowed": True,
    }


@pytest.mark.parametrize("kind", ["extensions", "presets", "workflows", "steps"])
def test_explicit_source_cannot_bypass_winning_catalog(tmp_path, monkeypatch, kind):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionCatalog
    from specify_cli.presets import PresetCatalog
    from specify_cli.workflows.catalog import StepCatalog, WorkflowCatalog

    catalogs = {
        "extensions": (ExtensionCatalog, "_locate_bundled_extension"),
        "presets": (PresetCatalog, "_locate_bundled_preset"),
        "workflows": (WorkflowCatalog, "_locate_bundled_workflow"),
        "steps": (StepCatalog, None),
    }
    catalog, asset = catalogs[kind]
    if asset:
        monkeypatch.setattr(assets, asset, lambda _id: None)
    fetches = []
    _patch_catalog_sources(
        monkeypatch, catalog, kind, [
            ("winning", {"catalog-id": {"version": "2.0.0"}}),
            ("lower", {"catalog-id": {"version": "1.0.0"}}),
        ], fetches,
    )
    component = ComponentRef(kind=kind, id="catalog-id", version="1.0.0", source="lower")

    with pytest.raises(BundlerError, match="winning"):
        primitive_manager(kind, tmp_path).install(component)
    assert fetches == ["winning"]


@pytest.mark.parametrize("kind", ["extensions", "presets", "workflows", "steps"])
def test_primitive_install_rejects_ambiguous_catalog_source(tmp_path, monkeypatch, kind):
    from specify_cli.extensions import CatalogEntry, ExtensionCatalog
    from specify_cli.presets import PresetCatalog, PresetCatalogEntry
    from specify_cli.workflows.catalog import (
        StepCatalog,
        StepCatalogEntry,
        WorkflowCatalog,
        WorkflowCatalogEntry,
    )

    catalog_type, entry_type = {
        "extensions": (ExtensionCatalog, CatalogEntry),
        "presets": (PresetCatalog, PresetCatalogEntry),
        "workflows": (WorkflowCatalog, WorkflowCatalogEntry),
        "steps": (StepCatalog, StepCatalogEntry),
    }[kind]
    sources = [
        entry_type("https://example.com/expected.json", "trusted", 1, True),
        entry_type("https://example.com/other.json", "trusted", 2, True),
    ]
    monkeypatch.setattr(catalog_type, "get_active_catalogs", lambda self: sources)
    monkeypatch.setattr(
        catalog_type,
        "_fetch_single_catalog",
        lambda *_args, **_kwargs: pytest.fail(
            "catalog fetch must not start with an ambiguous source"
        ),
    )

    with pytest.raises(BundlerError, match="ambiguous catalog source"):
        primitive_manager(kind, tmp_path).install(
            ComponentRef(kind=kind, id="catalog-id", source="trusted")
        )


@pytest.mark.parametrize("kind", ["workflows", "steps"])
def test_missing_exact_release_never_delegates_install(tmp_path, monkeypatch, kind):
    import specify_cli
    import specify_cli._assets as assets
    from specify_cli.workflows import command_add as workflow_add
    from specify_cli.workflows.step import command_add as step_add

    if kind == "workflows":
        monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda _id: None)
    command = (
        "workflow_add"
        if kind == "workflows"
        else "workflow_step_add"
    )
    _patch_winning_entry(monkeypatch, {
        "id": "catalog-id", "version": "2.0.0", "_catalog_name": "winning",
        "_install_allowed": True,
    })
    calls = []
    monkeypatch.setattr(specify_cli, command, lambda *a, **k: calls.append((a, k)))
    monkeypatch.setattr(
        workflow_add if kind == "workflows" else step_add,
        "_install_preselected_workflow" if kind == "workflows" else "_install_preselected_step",
        lambda *a, **k: calls.append((a, k)),
    )

    with pytest.raises(BundlerError, match="no catalog release"):
        primitive_manager(kind, tmp_path).install(
            ComponentRef(kind=kind, id="catalog-id", version="1.0.0")
        )
    assert calls == []


def test_bundled_workflow_with_older_pin_uses_catalog_release(tmp_path, monkeypatch):
    import specify_cli._assets as assets
    from specify_cli.workflows import _commands as workflow_cli

    (tmp_path / ".specify").mkdir()
    bundled = _write_manifest(tmp_path / "bundled", "workflow", "2.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda _id: bundled)
    _patch_winning_entry(monkeypatch, {
        **_workflow_or_step_entry("workflows", "x"),
        "_catalog_name": "winning", "_install_allowed": True,
    })
    calls = []
    monkeypatch.setattr(
        workflow_cli, "_install_workflow_from_catalog",
        lambda project_root, workflows_dir, source, **options:
            calls.append((source, options)),
    )

    primitive_manager("workflows", tmp_path).install(
        ComponentRef(kind="workflows", id="x", version="1.0.0")
    )

    assert calls == [("x", {
        "requested_version": "1.0.0",
        "selected_info": {
            "id": "x", "version": "1.0.0", "_catalog_name": "winning",
            "_install_allowed": True,
            **_workflow_or_step_entry("workflows", "x")["releases"]["1.0.0"],
        },
    })]


def test_source_on_bundled_extension_requires_catalog(tmp_path, monkeypatch):
    import specify_cli._assets as assets

    monkeypatch.setattr(
        assets, "_locate_bundled_extension",
        lambda _id: _write_manifest(tmp_path / "bundled", "extension", "1.0.0"),
    )
    _patch_winning_entry(monkeypatch, {
        "version": "1.0.0", "_catalog_name": "other",
        "_install_allowed": True,
    })
    with pytest.raises(BundlerError, match="other"):
        primitive_manager("extensions", tmp_path).install(
            ComponentRef(
                kind="extensions", id="x", version="1.0.0", source="expected"
            )
        )


def test_default_installer_threads_allow_network(tmp_path: Path):
    installer = DefaultPrimitiveInstaller(allow_network=False)
    with pytest.raises(BundlerError, match="network access is disabled"):
        installer.install(tmp_path, _component("workflows"))


@pytest.mark.parametrize("kind", ["presets", "extensions", "workflows", "steps"])
def test_offline_refresh_explains_component_needs_network(tmp_path: Path, kind: str):
    installer = DefaultPrimitiveInstaller(allow_network=False)
    with pytest.raises(BundlerError) as exc:
        installer.refresh(tmp_path, _component(kind, "definitely-not-bundled"))
    message = str(exc.value)
    assert "definitely-not-bundled" in message
    assert "refreshing this component requires network access" in message
    assert "re-run without --offline" in message
    assert "install it first" not in message


_REGISTRIES = {
    "extensions": lambda root: ExtensionRegistry(root / ".specify" / "extensions"),
    "presets": lambda root: PresetRegistry(root / ".specify" / "presets"),
    "workflows": WorkflowRegistry,
    "steps": StepRegistry,
}


@pytest.mark.parametrize("kind", sorted(_REGISTRIES))
def test_installed_version_reads_each_primitive_registry(tmp_path: Path, kind: str):
    _REGISTRIES[kind](tmp_path).add("x", {"version": "0.9.0"})
    installer = DefaultPrimitiveInstaller()

    assert installer.installed_version(tmp_path, _component(kind)) == "0.9.0"
    assert installer.installed_version(tmp_path, _component(kind, "missing")) is None


def test_offline_workflow_allows_bundled(tmp_path: Path, monkeypatch):
    # A workflow that ships with Spec Kit must install even with --offline.
    import specify_cli
    import specify_cli._assets as assets

    bundled = tmp_path / "wf"
    bundled.mkdir()
    (bundled / "workflow.yml").write_text(
        "workflow:\n  id: bundled-wf\n  version: 1.0.0\n", encoding="utf-8"
    )
    monkeypatch.setattr(
        assets, "_locate_bundled_workflow", lambda wid: bundled
    )
    calls: list[tuple] = []

    def _workflow_add(wid, dev=None, from_url=None):
        calls.append((wid, dev, from_url))

    monkeypatch.setattr(
        specify_cli,
        "workflow_add",
        _workflow_add,
    )

    manager = primitive_manager("workflows", tmp_path, allow_network=False)
    manager.install(_component("workflows", "bundled-wf"))

    assert calls == [(str(bundled / "workflow.yml"), True, None)]


def test_assert_pinned_version_matches_passes():
    from specify_cli.bundles.primitives import _assert_pinned_version

    # Equal (including v-prefix/normalization) is accepted; no version pins are no-ops.
    _assert_pinned_version("Preset", "p", "2.0.0", "2.0.0")
    _assert_pinned_version("Preset", "p", "2.0.0", "v2.0.0")
    _assert_pinned_version("Preset", "p", None, "9.9.9")
    _assert_pinned_version("Preset", "p", "2.0.0", None)


def test_assert_pinned_version_mismatch_raises():
    from specify_cli.bundles.primitives import _assert_pinned_version

    with pytest.raises(BundlerError, match="pinned to version 2.0.0"):
        _assert_pinned_version("Preset", "preset-a", "2.0.0", "3.1.0")


def test_workflow_version_mismatch_refuses(tmp_path: Path, monkeypatch):
    _patch_winning_entry(monkeypatch, {
        "id": "wf-a", "version": "9.9.9", "_catalog_name": "trusted",
        "_install_allowed": True,
    })
    manager = primitive_manager("workflows", tmp_path, allow_network=True)
    component = ComponentRef(kind="workflows", id="wf-a", version="0.3.0")
    with pytest.raises(BundlerError, match="no catalog release for pinned version 0.3.0"):
        manager.install(component)


def test_preset_install_preserves_explicit_zero_priority(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets

    calls = {}

    class _FakeManager:
        def install_from_directory(self, directory, speckit_version, priority):
            calls["priority"] = priority

    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda cid: tmp_path)

    manager = primitive_manager("presets", tmp_path, allow_network=False)
    manager._manager = _FakeManager()
    manager.install(ComponentRef(kind="presets", id="p", priority=0))

    # An explicit priority of 0 must be passed through, not replaced by default.
    assert calls["priority"] == 0


def test_catalog_preset_install_and_refresh_forward_catalog_name(
    tmp_path: Path, monkeypatch
):
    import specify_cli._assets as assets
    from specify_cli.presets import PresetCatalog

    archive = tmp_path / "preset.zip"
    archive.write_bytes(b"placeholder")
    calls = []

    class _FakeManager:
        def install_from_zip(self, *args, **kwargs):
            calls.append(kwargs)

    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda _id: None)
    _patch_winning_entry(monkeypatch, {
        "version": "1.0.0",
        "_install_allowed": True,
        "_catalog_name": "bundle-preset-catalog",
    })
    monkeypatch.setattr(
        PresetCatalog, "download_pack_info", lambda _self, _info: archive
    )

    manager = primitive_manager("presets", tmp_path, allow_network=True)
    manager._manager = _FakeManager()
    component = ComponentRef(kind="presets", id="catalog-preset", version="1.0.0")
    manager.install(component)
    archive.write_bytes(b"placeholder")
    manager.refresh(component)

    assert [call["catalog_name"] for call in calls] == [
        "bundle-preset-catalog",
        "bundle-preset-catalog",
    ]
    assert calls[1]["force"] is True


def test_catalog_extension_install_and_refresh_forward_catalog_and_scaffolding(
    tmp_path: Path, monkeypatch
):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionCatalog

    archive = tmp_path / "extension.zip"
    archive.write_bytes(b"placeholder")
    installs = []
    scaffolded = []

    class _FakeManager:
        def install_from_zip(self, *args, **kwargs):
            installs.append(kwargs)
            return SimpleNamespace(id="catalog-extension")

        def scaffold_config(self, extension_id):
            scaffolded.append(extension_id)

    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda _id: None)
    _patch_winning_entry(monkeypatch, {
        "version": "1.0.0",
        "_install_allowed": True,
        "_catalog_name": "bundle-extension-catalog",
    })
    monkeypatch.setattr(
        ExtensionCatalog, "download_extension_info", lambda _self, _info: archive
    )

    manager = primitive_manager("extensions", tmp_path, allow_network=True)
    manager._manager = _FakeManager()
    component = ComponentRef(
        kind="extensions", id="catalog-extension", version="1.0.0"
    )
    manager.install(component)
    archive.write_bytes(b"placeholder")
    manager.refresh(component)

    assert [call["catalog_name"] for call in installs] == [
        "bundle-extension-catalog",
        "bundle-extension-catalog",
    ]
    assert installs[1]["force"] is True
    assert scaffolded == ["catalog-extension", "catalog-extension"]


def _write_manifest(path: Path, root_key: str, version: str) -> Path:
    path.mkdir(parents=True, exist_ok=True)
    (path / f"{root_key}.yml").write_text(
        f"{root_key}:\n  id: x\n  version: {version}\n", encoding="utf-8"
    )
    return path


@pytest.mark.parametrize("kind", ["extensions", "presets", "workflows"])
@pytest.mark.parametrize("action", ["install", "refresh"])
def test_bundled_newer_patch_warns(
    tmp_path: Path, monkeypatch, capsys, kind: str, action: str,
):
    import specify_cli
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager
    from specify_cli.presets import PresetManager

    bundled = _write_manifest(tmp_path / "payload", kind[:-1], "1.0.1")
    monkeypatch.setattr(assets, f"_locate_bundled_{kind[:-1]}", lambda cid: bundled)
    calls = []
    if kind == "workflows":
        monkeypatch.setattr(specify_cli, "workflow_add", lambda *a, **kw: calls.append(a))
    else:
        manager_type = ExtensionManager if kind == "extensions" else PresetManager

        def install(self, *args, **kwargs):
            calls.append(args)
            return SimpleNamespace(id="x")

        monkeypatch.setattr(manager_type, "install_from_directory", install)
        if kind == "extensions":
            monkeypatch.setattr(manager_type, "scaffold_config", lambda *a: None)
    manager = primitive_manager(kind, tmp_path, allow_network=False)

    warning = getattr(manager, action)(ComponentRef(kind=kind, id="x", version="1.0.0"))

    assert len(calls) == 1
    assert warning is not None
    assert warning.code == "bundled_patch_upgrade"
    assert warning.details.kind == kind
    assert warning.details.component_id == "x"
    assert warning.details.requested_version == "1.0.0"
    assert warning.details.installed_version == "1.0.1"
    assert capsys.readouterr() == ("", "")


@pytest.mark.parametrize("actual", [
    "0.9.9", "1.0.0", "1.1.0", "2.0.0", "1.0.2-rc1", "1.0.2-alpha.1",
])
def test_bundled_extension_incompatible_versions_still_refuse(
    tmp_path: Path, monkeypatch, actual: str,
):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "payload", "extension", actual)
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    calls = []
    monkeypatch.setattr(
        ExtensionManager, "install_from_directory", lambda *a, **kw: calls.append(a),
    )
    manager = primitive_manager("extensions", tmp_path, allow_network=False)

    with pytest.raises(BundlerError, match="pinned to version 1.0.1"):
        manager.install(ComponentRef(kind="extensions", id="x", version="1.0.1"))
    assert calls == []


def test_catalog_extension_newer_patch_still_refuses(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionCatalog

    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: None)
    _patch_winning_entry(monkeypatch, {"version": "1.0.1"})
    downloads = []
    monkeypatch.setattr(
        ExtensionCatalog, "download_extension_info", lambda *a: downloads.append(a),
    )
    manager = primitive_manager("extensions", tmp_path)
    with pytest.raises(BundlerError, match="pinned to version 1.0.0"):
        manager.install(ComponentRef(kind="extensions", id="x", version="1.0.0"))
    assert downloads == []


def test_explicit_source_does_not_relax_bundled_pin(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets

    bundled = _write_manifest(tmp_path / "payload", "extension", "1.0.1")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    _patch_winning_entry(
        monkeypatch, {"version": "1.0.1", "_catalog_name": "custom-catalog"},
    )
    manager = primitive_manager("extensions", tmp_path)

    with pytest.raises(BundlerError, match="pinned to version 1.0.0"):
        manager.install(ComponentRef(
            kind="extensions", id="x", version="1.0.0", source="custom-catalog",
        ))


@pytest.mark.parametrize("actual,compatible", [
    ("1.0.1", True), ("1.0.2", False), ("1.0.0", False), ("1.1.0", False),
])
def test_installed_patch_must_match_packaged_version(
    tmp_path: Path, monkeypatch, actual: str, compatible: bool,
):
    import specify_cli._assets as assets

    bundled = _write_manifest(tmp_path / "payload", "extension", "1.0.1")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    installer = DefaultPrimitiveInstaller(allow_network=False)

    warning = installer.bundled_patch_warning(
        ComponentRef(kind="extensions", id="x", version="1.0.0"), actual,
    )
    assert (warning is not None) is compatible


def test_bundled_extension_pin_mismatch_refuses(tmp_path: Path, monkeypatch):
    """A bundled extension whose version != the manifest pin must be refused
    (the bundled path previously skipped the pin the catalog path enforces)."""
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "ext", "extension", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    called: list = []
    monkeypatch.setattr(
        ExtensionManager, "install_from_directory",
        lambda self, *a, **k: called.append(a),
    )

    manager = primitive_manager("extensions", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="pinned to version 2.0.0"):
        manager.install(ComponentRef(kind="extensions", id="my-ext", version="2.0.0"))
    assert called == []  # install must not proceed


def test_bundled_extension_pin_match_installs(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "ext", "extension", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    called: list = []

    def _fake_install(self, *a, **k):
        called.append(a)
        return SimpleNamespace(id="my-ext")

    monkeypatch.setattr(ExtensionManager, "install_from_directory", _fake_install)

    manager = primitive_manager("extensions", tmp_path, allow_network=False)
    # matching pin, and unpinned, both install cleanly
    manager.install(ComponentRef(kind="extensions", id="my-ext", version="1.0.0"))
    manager.install(ComponentRef(kind="extensions", id="my-ext", version=None))
    assert len(called) == 2


def _write_extension_with_config(ext_dir: Path) -> None:
    """A minimal, real (unmocked) extension source with a provides.config entry."""
    import yaml

    ext_dir.mkdir(parents=True, exist_ok=True)
    manifest = {
        "schema_version": "1.0",
        "extension": {
            "id": "my-ext",
            "name": "My Extension",
            "version": "1.0.0",
            "description": "Test extension",
        },
        "requires": {"speckit_version": ">=0.1.0"},
        "provides": {
            "commands": [
                {"name": "speckit.my-ext.hello", "file": "commands/hello.md"},
            ],
            "config": [
                {"name": "my-ext-config.yml", "template": "config-template.yml"},
            ],
        },
    }
    (ext_dir / "extension.yml").write_text(yaml.dump(manifest), encoding="utf-8")
    (ext_dir / "config-template.yml").write_text("setting: default\n", encoding="utf-8")
    (ext_dir / "commands").mkdir(exist_ok=True)
    (ext_dir / "commands" / "hello.md").write_text("---\ndescription: Test\n---\n\nhi\n", encoding="utf-8")


def test_bundled_extension_install_scaffolds_config(tmp_path: Path, monkeypatch):
    """A bundle-installed extension must have its provides.config templates
    scaffolded, exactly like `specify extension add` does (issue: bundle
    install skipped ExtensionManager.scaffold_config)."""
    import specify_cli._assets as assets

    project = tmp_path / "project"
    ext_source = tmp_path / "ext-source"
    _write_extension_with_config(ext_source)
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: ext_source)

    manager = primitive_manager("extensions", project, allow_network=False)
    manager.install(ComponentRef(kind="extensions", id="my-ext"))

    scaffolded = project / ".specify" / "extensions" / "my-ext" / "my-ext-config.yml"
    assert scaffolded.exists()
    assert scaffolded.read_text(encoding="utf-8") == "setting: default\n"


def test_catalog_extension_install_scaffolds_config(tmp_path: Path, monkeypatch):
    """A catalog-resolved (downloaded ZIP) extension install must also
    scaffold its provides.config templates, matching the bundled-directory
    coverage above. Exercises the reported reproduction, which installed an
    extension resolved from the catalog rather than one shipped with Spec Kit."""
    import zipfile

    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionCatalog

    project = tmp_path / "project"
    ext_source = tmp_path / "ext-source"
    _write_extension_with_config(ext_source)

    zip_path = tmp_path / "my-ext.zip"
    with zipfile.ZipFile(zip_path, "w") as zf:
        for f in ext_source.rglob("*"):
            if f.is_file():
                zf.write(f, f.relative_to(ext_source))

    # No bundled asset located: forces the catalog/ZIP branch (install_from_zip).
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: None)
    _patch_winning_entry(monkeypatch, {"id": "my-ext", "_install_allowed": True})
    monkeypatch.setattr(
        ExtensionCatalog, "download_extension_info", lambda self, info: zip_path
    )

    manager = primitive_manager("extensions", project, allow_network=True)
    manager.install(ComponentRef(kind="extensions", id="my-ext"))

    scaffolded = project / ".specify" / "extensions" / "my-ext" / "my-ext-config.yml"
    assert scaffolded.exists()
    assert scaffolded.read_text(encoding="utf-8") == "setting: default\n"


def test_bundled_preset_pin_mismatch_refuses(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets
    from specify_cli.presets import PresetManager

    bundled = _write_manifest(tmp_path / "preset", "preset", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda cid: bundled)
    called: list = []
    monkeypatch.setattr(
        PresetManager, "install_from_directory",
        lambda self, *a, **k: called.append(a),
    )

    manager = primitive_manager("presets", tmp_path, allow_network=False)
    with pytest.raises(BundlerError, match="pinned to version 2.0.0"):
        manager.install(ComponentRef(kind="presets", id="my-preset", version="2.0.0"))
    assert called == []


def test_bundled_preset_pin_match_installs(tmp_path: Path, monkeypatch):
    import specify_cli._assets as assets
    from specify_cli.presets import PresetManager

    bundled = _write_manifest(tmp_path / "preset", "preset", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda cid: bundled)
    called: list = []
    monkeypatch.setattr(
        PresetManager, "install_from_directory",
        lambda self, *a, **k: called.append(a),
    )

    manager = primitive_manager("presets", tmp_path, allow_network=False)
    # matching pin, and unpinned, both proceed to install
    manager.install(ComponentRef(kind="presets", id="my-preset", version="1.0.0"))
    manager.install(ComponentRef(kind="presets", id="my-preset", version=None))
    assert len(called) == 2


def test_extension_refresh_calls_install_with_force(tmp_path: Path, monkeypatch):
    """_ExtensionKindManager.refresh() must pass force=True to install_from_directory
    so an already-installed extension is overwritten instead of raising an error."""
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "ext", "extension", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    force_values: list = []

    def _fake_install(self, *a, **k):
        force_values.append(k.get("force", False))
        return SimpleNamespace(id="my-ext")

    monkeypatch.setattr(ExtensionManager, "install_from_directory", _fake_install)

    manager = primitive_manager("extensions", tmp_path, allow_network=False)
    manager.refresh(ComponentRef(kind="extensions", id="my-ext"))
    assert force_values == [True], "refresh() must pass force=True"


def test_preset_refresh_calls_install_with_force(tmp_path: Path, monkeypatch):
    """_PresetKindManager.refresh() must pass force=True to install_from_directory
    so an already-installed preset is overwritten instead of raising an error."""
    import specify_cli._assets as assets
    from specify_cli.presets import PresetManager

    bundled = _write_manifest(tmp_path / "preset", "preset", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda cid: bundled)
    force_values: list = []
    monkeypatch.setattr(
        PresetManager, "install_from_directory",
        lambda self, *a, **k: force_values.append(k.get("force", False)),
    )

    manager = primitive_manager("presets", tmp_path, allow_network=False)
    manager.refresh(ComponentRef(kind="presets", id="my-preset"))
    assert force_values == [True], "refresh() must pass force=True"


def test_default_installer_refresh_dispatches_to_kind_manager(tmp_path: Path, monkeypatch):
    """DefaultPrimitiveInstaller.refresh() must call the kind manager's refresh(),
    which is the hook _refresh_component() will find β€” fixing the --force leak."""
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "ext", "extension", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    force_values: list = []

    def _fake_install(self, *a, **k):
        force_values.append(k.get("force", False))
        return SimpleNamespace(id="my-ext")

    monkeypatch.setattr(ExtensionManager, "install_from_directory", _fake_install)

    installer = DefaultPrimitiveInstaller(allow_network=False)
    installer.refresh(tmp_path, _component("extensions", "my-ext"))
    assert force_values == [True], "DefaultPrimitiveInstaller.refresh() must use force=True"


def test_refresh_succeeds_and_passes_force_true(tmp_path: Path, monkeypatch):
    """Regression: bundle update (refresh=True) of an already-installed extension
    must succeed and pass force=True to install_from_directory."""
    import specify_cli._assets as assets
    from specify_cli.bundles.installer import install_bundle
    from specify_cli.bundles.manifest import BundleManifest
    from specify_cli.extensions import ExtensionManager

    bundled = _write_manifest(tmp_path / "ext", "extension", "1.0.0")
    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
    # Simulate refresh succeeding (force=True removes the duplicate-install guard)
    force_seen: list = []
    def _fake_install_from_directory(self, *a, **k):
        force_seen.append(k.get("force", False))
        self.registry.add("my-ext", {"version": "1.0.0"})
        return SimpleNamespace(id="my-ext")

    monkeypatch.setattr(
        ExtensionManager, "install_from_directory", _fake_install_from_directory
    )

    raw = valid_manifest_dict(
        bundle={
            "id": "test-bundle",
            "name": "Test",
            "version": "1.0.0",
            "role": "developer",
            "description": "Test bundle",
            "author": "Spec Kit",
            "license": "MIT",
        },
        provides={
            "extensions": [{"id": "my-ext", "version": "1.0.0"}],
            "presets": [],
            "steps": [],
            "workflows": [],
        },
    )
    manifest = BundleManifest.from_dict(raw)
    installer = DefaultPrimitiveInstaller(allow_network=False)
    # First install
    install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
    # Refresh (bundle update) β€” must not raise with --force hint
    install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest, refresh=True)
    # force=True must have been passed during the refresh call
    assert True in force_seen, "refresh path should have called install_from_directory with force=True"


def _plan(manifest):
    from specify_cli.bundles.installer import InstallPlan
    from specify_cli.bundles.manifest import ComponentRef as CR

    components = [CR(kind=c.kind, id=c.id) for c in manifest.components]
    return InstallPlan(
        bundle_id=manifest.bundle.id,
        version=manifest.bundle.version,
        role=manifest.bundle.role,
        effective_integration=None,
        components=components,
    )


@pytest.mark.parametrize("failure_stage", ["installer", "catalog"])
def test_step_refresh_restores_registry_entry_when_reinstall_fails(
    tmp_path: Path, monkeypatch, failure_stage
):
    """A failed step refresh must leave the registry entry restored.

    ``refresh`` keeps a backup and restores it "if the remove+reinstall path
    fails", but the registry half of that rollback was unreachable:
    ``StepRegistry`` snapshots the file once in ``__init__`` and
    ``is_installed`` reads only that snapshot, so after ``self.remove()``
    deleted the entry from disk the stale snapshot still reported it as
    installed and ``not ...is_installed(...)`` was always False.

    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".
    """
    import json

    from specify_cli.bundles import primitives
    from specify_cli.workflows.catalog import StepCatalogError, StepRegistry
    from specify_cli.workflows.step import command_add
    from specify_cli.workflows.step.installer import StepInstallError

    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": {
                        "name": "My Step",
                        "version": "1.0.0",
                        "type_key": "my-step",
                        # Distinctive past timestamps: a rollback must put the
                        # entry back verbatim, and ``StepRegistry.add()`` would
                        # silently replace both of these with ``now``.
                        "installed_at": "2020-01-01T00:00:00+00:00",
                        "updated_at": "2020-02-02T00:00:00+00:00",
                    }
                },
            }
        ),
        encoding="utf-8",
    )

    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.
    def _boom(step_id, *args, **kwargs):
        raise StepInstallError(f"Failed to install step '{step_id}'.")

    if failure_stage == "catalog":
        def _catalog_failure(*args):
            raise StepCatalogError("catalog became unreachable")

        monkeypatch.setattr(primitives, "_selected_catalog_info", _catalog_failure)
    else:
        monkeypatch.setattr(primitives, "_selected_catalog_info", lambda *args: {
            "_catalog_name": "trusted",
        })
        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"), (
        steps_dir / StepRegistry.REGISTRY_FILE
    ).read_text(encoding="utf-8")
    # 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()


@pytest.mark.parametrize("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


def _versioned_entry(cid: str) -> dict:
    """A catalog entry advertising 0.5.1 that keeps 0.4.12 under ``releases``."""
    return {
        "id": cid,
        "name": cid,
        "version": "0.5.1",
        "download_url": f"https://example.com/{cid}/v0.5.1/{cid}.zip",
        "sha256": "b" * 64,
        "releases": {
            "0.4.12": {
                "download_url": f"https://example.com/{cid}/v0.4.12/{cid}.zip",
                "sha256": _HISTORICAL_SHA,
            }
        },
        "_install_allowed": True,
        "_catalog_name": "bundle-catalog",
    }


def _patch_extension_catalog(monkeypatch, entry: dict, archive: Path, downloads: list):
    import specify_cli._assets as assets
    from specify_cli.extensions import ExtensionCatalog

    monkeypatch.setattr(assets, "_locate_bundled_extension", lambda _id: None)
    _patch_winning_entry(monkeypatch, entry)
    monkeypatch.setattr(
        ExtensionCatalog, "get_extension_info",
        lambda *args, **kwargs: pytest.fail("extension catalog was re-resolved"),
    )

    def _download(_self, info):
        downloads.append(info)
        return archive

    monkeypatch.setattr(ExtensionCatalog, "download_extension_info", _download)


def _patch_preset_catalog(monkeypatch, entry: dict, archive: Path, downloads: list):
    import specify_cli._assets as assets
    from specify_cli.presets import PresetCatalog

    monkeypatch.setattr(assets, "_locate_bundled_preset", lambda _id: None)
    _patch_winning_entry(monkeypatch, entry)
    monkeypatch.setattr(
        PresetCatalog, "get_pack_info",
        lambda *args, **kwargs: pytest.fail("preset catalog was re-resolved"),
    )

    def _download(_self, info):
        downloads.append(info)
        return archive

    monkeypatch.setattr(PresetCatalog, "download_pack_info", _download)


def test_extension_pin_selects_historical_catalog_release(tmp_path: Path, monkeypatch):
    """A pin older than the advertised release installs that exact release
    (its own URL and digest) instead of refusing the install (#4712)."""
    archive = tmp_path / "ext.zip"
    archive.write_bytes(b"placeholder")
    downloads: list = []
    installs: list = []
    _patch_extension_catalog(
        monkeypatch, _versioned_entry("pinned-ext"), archive, downloads
    )

    class _FakeManager:
        def install_from_zip(self, *args, **kwargs):
            installs.append(kwargs)
            return SimpleNamespace(id="pinned-ext")

        def scaffold_config(self, _extension_id):
            pass

    manager = primitive_manager("extensions", tmp_path, allow_network=True)
    manager._manager = _FakeManager()
    manager.install(ComponentRef(kind="extensions", id="pinned-ext", version="0.4.12"))

    assert [d["version"] for d in downloads] == ["0.4.12"]
    assert downloads[0]["download_url"].endswith("/v0.4.12/pinned-ext.zip")
    assert downloads[0]["sha256"] == _HISTORICAL_SHA
    assert installs[0]["expected_id"] == "pinned-ext"
    assert installs[0]["expected_version"] == "0.4.12"
    assert installs[0]["catalog_name"] == "bundle-catalog"


def test_preset_pin_selects_historical_catalog_release(tmp_path: Path, monkeypatch):
    archive = tmp_path / "preset.zip"
    archive.write_bytes(b"placeholder")
    downloads: list = []
    installs: list = []
    _patch_preset_catalog(
        monkeypatch, _versioned_entry("pinned-preset"), archive, downloads
    )

    class _FakeManager:
        def install_from_zip(self, *args, **kwargs):
            installs.append(kwargs)

    manager = primitive_manager("presets", tmp_path, allow_network=True)
    manager._manager = _FakeManager()
    manager.install(ComponentRef(kind="presets", id="pinned-preset", version="0.4.12"))

    assert [d["version"] for d in downloads] == ["0.4.12"]
    assert downloads[0]["download_url"].endswith("/v0.4.12/pinned-preset.zip")
    assert downloads[0]["sha256"] == _HISTORICAL_SHA
    assert installs[0]["expected_id"] == "pinned-preset"
    assert installs[0]["expected_version"] == "0.4.12"


@pytest.mark.parametrize("kind", ["extensions", "presets"])
def test_pin_missing_from_catalog_releases_refuses_before_download(
    tmp_path: Path, monkeypatch, kind: str
):
    """A pin the winning catalog entry does not carry fails clearly, without
    substituting the advertised release."""
    archive = tmp_path / "a.zip"
    downloads: list = []
    patch = _patch_extension_catalog if kind == "extensions" else _patch_preset_catalog
    patch(monkeypatch, _versioned_entry("c"), archive, downloads)

    manager = primitive_manager(kind, tmp_path, allow_network=True)
    with pytest.raises(
        BundlerError,
        match=r"pinned to version 0\.3\.0 .* no release for that version "
        r"\(it advertises 0\.5\.1\)",
    ):
        manager.install(ComponentRef(kind=kind, id="c", version="0.3.0"))
    assert downloads == []


@pytest.mark.parametrize("kind", ["extensions", "presets"])
def test_unpinned_component_installs_advertised_release_unverified(
    tmp_path: Path, monkeypatch, kind: str
):
    archive = tmp_path / "a.zip"
    archive.write_bytes(b"placeholder")
    downloads: list = []
    installs: list = []
    patch = _patch_extension_catalog if kind == "extensions" else _patch_preset_catalog
    patch(monkeypatch, _versioned_entry("c"), archive, downloads)

    class _FakeManager:
        def install_from_zip(self, *args, **kwargs):
            installs.append(kwargs)
            return SimpleNamespace(id="c")

        def scaffold_config(self, _extension_id):
            pass

    manager = primitive_manager(kind, tmp_path, allow_network=True)
    manager._manager = _FakeManager()
    manager.install(ComponentRef(kind=kind, id="c"))

    assert [d["version"] for d in downloads] == ["0.5.1"]
    assert "expected_version" not in installs[0]


def test_extension_pin_refuses_archive_declaring_another_version(
    tmp_path: Path, monkeypatch
):
    """The selected release's archive must declare the pinned version: a
    mislabeled historical asset is refused and nothing is installed."""
    import zipfile

    from specify_cli.extensions import ExtensionError

    project = tmp_path / "project"
    ext_source = tmp_path / "ext-source"
    _write_extension_with_config(ext_source)  # declares my-ext 1.0.0
    zip_path = tmp_path / "my-ext.zip"
    with zipfile.ZipFile(zip_path, "w") as zf:
        for f in ext_source.rglob("*"):
            if f.is_file():
                zf.write(f, f.relative_to(ext_source))

    entry = _versioned_entry("my-ext")
    _patch_extension_catalog(monkeypatch, entry, zip_path, [])

    manager = primitive_manager("extensions", project, allow_network=True)
    with pytest.raises(ExtensionError, match="0.4.12"):
        manager.install(ComponentRef(kind="extensions", id="my-ext", version="0.4.12"))
    assert not manager.is_installed(ComponentRef(kind="extensions", id="my-ext"))
    assert not zip_path.exists()