π« Toolkit to help you get started with SDD or any other process!
"""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()