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

* fix(bundler): resolve built-in step types when checking bundle references

`_resolved_locally` gives three of the four component kinds a
"is it bundled with Spec Kit?" check before the installed-in-project one:

  presets    -> _locate_bundled_preset   or PresetManager.get_pack
  extensions -> _locate_bundled_extension or ExtensionManager...is_installed
  workflows  -> _locate_bundled_workflow  or WorkflowRegistry.is_installed
  steps      -> StepRegistry.is_installed          <-- no bundled check

`StepRegistry` tracks *community* step types installed under
`.specify/workflows/steps/`. Spec Kit ships 11 step types as built-ins
registered in `STEP_REGISTRY`, so every one of them looked unresolved:

  steps/shell   -> False
  steps/gate    -> False
  steps/command -> False
  steps/if      -> False

A bundle declaring a dependency on any built-in step type was therefore
reported as an unresolved reference — an error online, a warning offline.

There is no `_locate_bundled_step` to mirror, because step types are not
an on-disk asset directory; `STEP_REGISTRY` is the equivalent check, and
is what `specify workflow step info` reports as "built-in".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(bundler): check an immutable built-in step set, not the mutable registry

Review catch: `STEP_REGISTRY` is not limited to bundled steps.
`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 while working on project A would be accepted as "bundled" when
validating a bundle for project B — before B's own StepRegistry is
consulted.

Snapshot the shipped ids into `BUILTIN_STEP_TYPES` immediately after
`_register_builtin_steps()`, before `load_custom_steps` is even defined,
and check that frozenset instead.

Verified: with the check on STEP_REGISTRY the new cross-project test fails
(a leaked community id resolves as bundled); with BUILTIN_STEP_TYPES it
passes. 1 failed, 5 passed -> 6 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: jawwad-ali

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

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.

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] = []