Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(bundler): resolve built-in step types when checking bundle component references (#3885)

Ali jawwad21fb1bbbb374
diff --git a/src/specify_cli/bundler/services/references.py b/src/specify_cli/bundler/services/references.py
index 3dd0f3d01..b5419237d 100644
--- a/src/specify_cli/bundler/services/references.py
+++ b/src/specify_cli/bundler/services/references.py
@@ -40,8 +40,21 @@ def _resolved_locally(root: Path, component: ComponentRef) -> bool:
return True
return WorkflowRegistry(root).is_installed(component.id)
if kind == "steps":
+ from ...workflows import BUILTIN_STEP_TYPES
from ...workflows.catalog import StepRegistry
+ # Step types ship with Spec Kit as built-ins (shell, gate, if, ...)
+ # rather than as an on-disk asset directory, so there is no
+ # ``_locate_bundled_step`` to mirror the three lookups above.
+ # ``BUILTIN_STEP_TYPES`` is the bundled-with-Spec-Kit check for this
+ # kind. Deliberately NOT ``STEP_REGISTRY``: ``load_custom_steps``
+ # adds project-installed ids to that process-global mapping and
+ # never removes them, so in a long-lived process a community step
+ # loaded for one project would be accepted as "bundled" when
+ # validating another. Without any bundled check at all, every
+ # built-in step type looked unresolved.
+ if component.id in BUILTIN_STEP_TYPES:
+ return True
return StepRegistry(root).is_installed(component.id)
except Exception: # noqa: BLE001 - resolution is best-effort
return False
diff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.py
index 8775428c5..0d1e101a9 100644
--- a/src/specify_cli/workflows/__init__.py
+++ b/src/specify_cli/workflows/__init__.py
@@ -71,6 +71,14 @@ def _register_builtin_steps() -> None:
_register_builtin_steps()
+# The step types Spec Kit ships, snapshotted before any community step can be
+# loaded. ``load_custom_steps`` adds project-installed ids to the process-global
+# ``STEP_REGISTRY`` and never removes them, so ``STEP_REGISTRY`` cannot answer
+# "is this bundled with Spec Kit?" in a long-lived process: a step loaded for one
+# project would look built-in for the next. Callers that need the immutable set
+# (e.g. the bundler's reference checker) must use this instead.
+BUILTIN_STEP_TYPES: frozenset[str] = frozenset(STEP_REGISTRY)
+
def load_custom_steps(project_root: Path) -> list[str]:
"""Load community-installed custom step types into STEP_REGISTRY.
diff --git a/tests/unit/test_bundler_references.py b/tests/unit/test_bundler_references.py
index 1291ba08b..b9ad42666 100644
--- a/tests/unit/test_bundler_references.py
+++ b/tests/unit/test_bundler_references.py
@@ -24,6 +24,77 @@ def test_bundled_extension_resolves(tmp_path: Path):
assert warnings == []
+def test_builtin_step_type_resolves(tmp_path: Path):
+ """A built-in step type must resolve, like a bundled extension.
+
+ Spec Kit ships 11 step types as built-ins registered in ``STEP_REGISTRY``
+ rather than as on-disk asset directories, so there is no
+ ``_locate_bundled_step``. The ``steps`` branch of ``_resolved_locally`` only
+ asked ``StepRegistry(root).is_installed()``, which tracks *community* step
+ types installed under ``.specify/workflows/steps/`` — so every built-in step
+ type was reported as an unresolved reference.
+ """
+ from specify_cli.workflows import BUILTIN_STEP_TYPES
+
+ root = make_project(tmp_path)
+ warnings: list[str] = []
+ check = make_reference_checker(root, allow_network=True, warnings=warnings)
+
+ for step_id in ("shell", "gate", "command", "if"):
+ assert step_id in BUILTIN_STEP_TYPES, step_id
+ assert check(_ref("steps", step_id)) is None, step_id
+ assert warnings == []
+
+
+def test_community_step_is_not_treated_as_bundled(tmp_path: Path):
+ """A community step loaded for one project must not resolve for another.
+
+ `load_custom_steps` adds project-installed ids to the process-global
+ `STEP_REGISTRY` and never removes them, so checking `STEP_REGISTRY` here
+ would accept project A's community step as "bundled" while validating
+ project B. `BUILTIN_STEP_TYPES` is snapshotted before any custom step can
+ load, which is why the check uses it instead.
+ """
+ from specify_cli.workflows import (
+ BUILTIN_STEP_TYPES,
+ STEP_REGISTRY,
+ _register_step,
+ )
+ from specify_cli.workflows.base import StepBase, StepResult, StepStatus
+
+ class _CommunityStep(StepBase):
+ type_key = "community-only-step"
+
+ def execute(self, config, context): # pragma: no cover - never run
+ return StepResult(status=StepStatus.COMPLETED)
+
+ # Simulate project A having loaded a community step into the global registry.
+ _register_step(_CommunityStep())
+ try:
+ assert "community-only-step" in STEP_REGISTRY
+ assert "community-only-step" not in BUILTIN_STEP_TYPES
+
+ # Project B does not have it installed, so it must NOT resolve locally.
+ root = make_project(tmp_path)
+ warnings: list[str] = []
+ check = make_reference_checker(root, allow_network=True, warnings=warnings)
+ problem = check(_ref("steps", "community-only-step"))
+ assert problem is not None, "leaked community step resolved as bundled"
+ assert "community-only-step" in problem
+ finally:
+ STEP_REGISTRY.pop("community-only-step", None)
+
+
+def test_unknown_step_type_still_errors_online(tmp_path: Path):
+ """The guard must not make every step id resolve."""
+ root = make_project(tmp_path)
+ warnings: list[str] = []
+ check = make_reference_checker(root, allow_network=True, warnings=warnings)
+ problem = check(_ref("steps", "no-such-step-type"))
+ assert problem is not None
+ assert "no-such-step-type" in problem
+
+
def test_unknown_reference_errors_online(tmp_path: Path):
root = make_project(tmp_path)
warnings: list[str] = []