π« Toolkit to help you get started with SDD or any other process!
Fix: scaffold self-contained namespaced preset commands (#4076) (#4082)
Manfred Rieme79fa25f3f46
diff --git a/src/specify_cli/presets/__init__.py b/src/specify_cli/presets/__init__.pyindex 6a359f5b2..3d37f6fb7 100644--- a/src/specify_cli/presets/__init__.py+++ b/src/specify_cli/presets/__init__.py@@ -823,25 +823,6 @@ class PresetManager:return True- def _extension_installed_for_command(self, command_name: str) -> bool:- """Whether *command_name* may be materialized in this project.-- Extension command overrides follow ``speckit.<ext-id>.<cmd-name>``;- they must be skipped everywhere preset artifacts are written β- registration *and* reconciliation β when the extension isn't- installed, or reconciliation would materialize files that- registration refused to track. Core commands (single-dot names,- e.g. ``speckit.specify``) always pass.- """- parts = command_name.split(".")- if len(parts) >= 3 and parts[0] == "speckit":- ext_id = parts[1]- if not (- self.project_root / ".specify" / "extensions" / ext_id- ).is_dir():- return False- return True-def _register_commands(self,manifest: PresetManifest,@@ -870,21 +851,20 @@ class PresetManager:if not command_templates:return {}- # Filter out extension command overrides if the extension isn't installed.- filtered = [- cmd- for cmd in command_templates- if self._extension_installed_for_command(cmd["name"])- ]-- if not filtered:- return {}-+ # A preset command template always ships its own body, so it is+ # self-contained and scaffolds regardless of whether any similarly+ # named extension is installed. Namespaced names (speckit.<ns>.<cmd>)+ # are treated exactly like short names (speckit.<cmd>) β they are NOT+ # filtered out just because ``.specify/extensions/<ns>/`` is absent.+ # The only command that cannot be materialized is a composition+ # (prepend/append/wrap) with no base layer to compose onto; that case+ # is handled per-command below (warn + skip), not by dropping names up+ # front.# Handle composition strategies: resolve composed content for non-replace commandsresolver = PresetResolver(self.project_root)composed_dir = Nonecommands_to_register = []- for cmd in filtered:+ for cmd in command_templates:strategy = cmd.get("strategy", "replace")if strategy != "replace":# Only pre-compose if this preset is the top composing layer.@@ -907,13 +887,23 @@ class PresetManager:"file": f".composed/{cmd['name']}.md",})else:- raise PresetValidationError(- f"Command '{cmd['name']}' uses '{strategy}' strategy "- f"but no base command layer exists to compose onto. "- f"Ensure a lower-priority preset, extension, or core "- f"command provides this command before using "- f"composition strategies."+ # No base layer to compose onto (e.g. the command it+ # would wrap comes from an extension that isn't+ # installed). Warn and skip this single command rather+ # than aborting the whole install β mirrors the+ # "composed is None" branch in+ # _reconcile_composed_commands so command-mode and+ # reconciliation behave identically.+ import warnings+ warnings.warn(+ f"Command '{cmd['name']}' uses '{strategy}' "+ f"strategy but no base command layer exists to "+ f"compose onto; skipping. Provide a lower-priority "+ f"preset, extension, or core command for it before "+ f"using composition strategies.",+ stacklevel=2,)+ continueelse:# Not the top layer β register raw file; reconciliation# will overwrite with the correct composed/winning content.@@ -1681,21 +1671,13 @@ class PresetManager:if not command_names:return set()- # Never materialize extension-scoped commands whose extension isn't- # installed. Registration (_register_commands / _register_skills)- # already refuses them, so a reconciliation pass writing them would- # create files no registry entry tracks. Filtering here β the single- # chokepoint every install/remove/rescaffold reconciliation funnels- # through β keeps all callers consistent without each one re-applying- # the filter when seeding names from manifest templates.- command_names = [- name- for name in command_names- if self._extension_installed_for_command(name)- ]- if not command_names:- return set()-+ # Every preset-owned command name flows through unchanged. Names are+ # NOT filtered by the ``speckit.<ns>.<cmd>`` shape: a self-contained+ # preset command scaffolds whether or not a like-named extension is+ # installed (parity with _register_commands), and a name whose base+ # layer has disappeared must still reach the loop below so its now+ # uncomposable stale file gets unregistered. The loop already skips+ # names that resolve to no layers at all (``if not layers: continue``).try:from ..agents import CommandRegistrarexcept ImportError:@@ -2136,14 +2118,11 @@ class PresetManager:if not command_names:return set()- command_names = [- name- for name in command_names- if self._extension_installed_for_command(name)- ]- if not command_names:- return set()-+ # Preset-owned command names are not filtered by the+ # ``speckit.<ns>.<cmd>`` shape here either: a self-contained preset+ # command renders its skill whether or not a like-named extension is+ # installed. The per-name loop below skips anything that doesn't+ # resolve to a managed skill directory.resolver = PresetResolver(self.project_root)active_skills_dir = self._get_skills_dir()@@ -2673,21 +2652,17 @@ class PresetManager:if not command_templates:return {}- # Filter out extension command overrides if the extension isn't installed,- # matching the same logic used by _register_commands().- filtered = [- cmd- for cmd in command_templates- if self._extension_installed_for_command(cmd["name"])- ]-- if not filtered:- return {}-+ # Preset command templates are self-contained and render as skills+ # regardless of whether a like-named extension is installed β the same+ # rule _register_commands() uses. No ``speckit.<ns>.<cmd>`` name-shape+ # filtering; the per-command loop below skips anything without a target+ # skill directory.skills_dir = target_dir if target_dir is not None else self._get_skills_dir()if not skills_dir:return {}+ resolver = PresetResolver(self.project_root)+from .. import SKILL_DESCRIPTIONS, load_init_optionsfrom ..agents import CommandRegistrarfrom ..integrations import get_integration@@ -2717,7 +2692,7 @@ class PresetManager:written: List[str] = []- for cmd_tmpl in filtered:+ for cmd_tmpl in command_templates:cmd_name = cmd_tmpl["name"]cmd_file_rel = cmd_tmpl["file"]source_file = preset_dir / cmd_file_rel@@ -2757,6 +2732,29 @@ class PresetManager:content = source_file.read_text(encoding="utf-8")frontmatter, body = registrar.parse_frontmatter(content)+ # A composition-strategy command (wrap/prepend/append) needs a+ # base layer to compose onto. When _register_commands produced no+ # composed file for it and the stack still has no base+ # (resolve_content is None) β e.g. the command it wraps comes from+ # an extension that isn't installed β rendering the raw preset+ # fragment as a skill would emit broken output: a literal+ # {CORE_TEMPLATE} for wrap, or only the preset's own fragment for+ # prepend/append. Skip it here too so command mode and skills mode+ # agree (mirrors _register_commands, which skips the same command).+ # _register_commands already warned for this command in the same+ # pass, so the skip is silent here to avoid a duplicate warning.+ effective_strategy = (+ cmd_tmpl.get("strategy")+ or frontmatter.get("strategy")+ or "replace"+ )+ if (+ effective_strategy != "replace"+ and not composed_file.exists()+ and resolver.resolve_content(cmd_name, "command") is None+ ):+ continue+if frontmatter.get("strategy") == "wrap":body, core_frontmatter = _substitute_core_template(body, cmd_name, self.project_root, registrar)frontmatter = dict(frontmatter)diff --git a/tests/test_presets.py b/tests/test_presets.pyindex 317a1b437..49c8f6e33 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -4260,8 +4260,14 @@ class TestSelfTestPreset:assert manifest.id == "invalid-wrap"assert manager.registry.is_installed("invalid-wrap")- def test_extension_command_skipped_when_extension_missing(self, project_dir, temp_dir):- """Test that extension command overrides are skipped if the extension isn't installed."""+ def test_selfcontained_namespaced_command_scaffolds_without_extension(self, project_dir, temp_dir):+ """A preset shipping a self-contained ``speckit.<ns>.<cmd>`` command+ scaffolds even when no matching extension is installed.++ The command template ships its own body, so it is self-contained and+ must render just like a short ``speckit.<cmd>`` command. It is not+ dropped merely because ``.specify/extensions/fakeext/`` is absent.+ """claude_dir = project_dir / ".claude" / "skills"claude_dir.mkdir(parents=True)@@ -4297,11 +4303,13 @@ class TestSelfTestPreset:manager = PresetManager(project_dir)manager.install_from_directory(preset_dir, "0.1.5")- # Extension not installed β command should NOT be registered- cmd_file = claude_dir / "speckit.fakeext.cmd.md"- assert not cmd_file.exists(), "Command registered for missing extension"+ # Extension not installed, but the preset ships its own command body β+ # it must scaffold (as a native-skill SKILL.md for claude) and be+ # tracked in the preset's registered_commands.+ skill_file = claude_dir / "speckit-fakeext-cmd" / "SKILL.md"+ assert skill_file.exists(), "Self-contained namespaced command was dropped"metadata = manager.registry.get("ext-override")- assert metadata["registered_commands"] == {}+ assert metadata["registered_commands"] != {}def test_extension_command_registered_when_extension_present(self, project_dir, temp_dir):"""Test that extension command overrides ARE registered when the extension is installed."""@@ -6528,17 +6536,16 @@ class TestPresetSkills:"sanity: the new skills-mode artifact should still be written")- def test_rescaffold_skips_extension_commands_when_extension_not_installed(+ def test_rescaffold_scaffolds_selfcontained_namespaced_commands(self, project_dir, temp_dir):- """Rescaffold must not materialize extension-scoped commands- (``speckit.<ext>.<cmd>``) when the extension isn't installed.-- ``_register_commands`` refuses them, but the rescaffold seeded its- final reconciliation pass with every command template name- unfiltered, so ``_reconcile_composed_commands`` wrote the command- file anyway β an artifact no registry entry tracks (review- 3623357358).+ """A self-contained ``speckit.<ns>.<cmd>`` preset command scaffolds and+ survives rescaffold, even when no matching extension is installed.++ The preset ships the command body itself, so it is materialized just+ like a short ``speckit.<cmd>`` command β both at install and through a+ later reconciliation/rescaffold pass. It is not dropped by the+ ``speckit.<ns>.<cmd>`` name shape (#4076)."""self._write_init_options(project_dir, ai="copilot", ai_skills=False)commands_dir = project_dir / ".github" / "agents"@@ -6552,24 +6559,24 @@ class TestPresetSkills:manager.install_from_directory(preset_dir, "0.1.5")ext_cmd = commands_dir / "speckit.git.feature.agent.md"- assert not ext_cmd.exists(), (- "sanity: install must not write an extension command when the "- "extension isn't installed"+ assert ext_cmd.exists(), (+ "sanity: install must scaffold a self-contained namespaced command "+ "even when its like-named extension isn't installed")manager.register_enabled_presets_for_agent("copilot")- assert not ext_cmd.exists(), (- "rescaffold must not materialize an extension-scoped command "- "whose extension isn't installed"+ assert ext_cmd.exists(), (+ "rescaffold must keep the self-contained namespaced command")metadata = manager.registry.get("ext-scoped-preset")- assert not (metadata.get("registered_commands") or {}).get("copilot")+ assert (metadata.get("registered_commands") or {}).get("copilot")- def test_rescaffold_skips_extension_skills_when_extension_not_installed(+ def test_rescaffold_scaffolds_selfcontained_namespaced_skills(self, project_dir, temp_dir):- """Historical tracking must not recreate a missing extension's skill."""+ """A self-contained ``speckit.<ns>.<cmd>`` preset command renders its+ skill even when no matching extension is installed."""self._write_init_options(project_dir, ai="copilot", ai_skills=True)skills_dir = project_dir / ".github" / "skills"skills_dir.mkdir(parents=True)@@ -6586,27 +6593,79 @@ class TestPresetSkills:skill_name = "speckit-git-feature"skill_file = skills_dir / skill_name / "SKILL.md"- assert not skill_file.exists()-- manager.registry.update(- "ext-scoped-skill-preset",- {"registered_skills": {"copilot": [skill_name]}},+ assert skill_file.exists(), (+ "install must render a self-contained namespaced command's skill "+ "even when its like-named extension isn't installed")- overrides_dir = (- project_dir / ".specify" / "templates" / "overrides"++ manager.register_enabled_presets_for_agent("copilot")++ assert skill_file.exists(), (+ "rescaffold must keep the self-contained namespaced command's skill")- overrides_dir.mkdir(parents=True)- (overrides_dir / "speckit.git.feature.md").write_text(- "---\ndescription: Project override\n---\n\nOverride body\n",- encoding="utf-8",++ def test_uncomposable_wrap_command_skips_skill_in_skills_mode(+ self, project_dir, temp_dir+ ):+ """A wrap command with no base layer must not materialize a broken+ skill in skills mode.++ When ``_register_commands`` skips an uncomposable wrap command (no+ base to compose onto β e.g. the command it wraps comes from an+ uninstalled extension), ``_register_skills`` must skip it too. Before+ this fix, skills mode fell back to the raw preset body and wrote a+ SKILL.md containing a literal ``{CORE_TEMPLATE}`` placeholder.+ """+ self._write_init_options(project_dir, ai="copilot", ai_skills=True)+ skills_dir = project_dir / ".github" / "skills"+ skills_dir.mkdir(parents=True)++ preset_dir = temp_dir / "uncomposable-wrap"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ # speckit.git.feature has no core command template and no installed+ # extension, so there is no base layer to wrap.+ (preset_dir / "commands" / "speckit.git.feature.md").write_text(+ "---\ndescription: Wrap\nstrategy: wrap\n---\n\n"+ "wrap start\n{CORE_TEMPLATE}\nwrap end\n")+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": "uncomposable-wrap",+ "name": "uncomposable-wrap",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.git.feature",+ "file": "commands/speckit.git.feature.md",+ "strategy": "wrap",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)- manager.register_enabled_presets_for_agent("copilot")+ manager = PresetManager(project_dir)+ with pytest.warns(UserWarning, match="no base command layer"):+ manager.install_from_directory(preset_dir, "0.1.5")+ skill_file = skills_dir / "speckit-git-feature" / "SKILL.md"assert not skill_file.exists(), (- "rescaffold must not materialize an extension-scoped skill "- "whose extension isn't installed"+ "an uncomposable wrap command must not be rendered as a skill")+ # Belt-and-suspenders: no artifact anywhere may leak the raw placeholder.+ leaked = [+ p for p in skills_dir.rglob("*")+ if p.is_file() and "{CORE_TEMPLATE}" in p.read_text(encoding="utf-8")+ ]+ assert not leaked, f"literal {{CORE_TEMPLATE}} leaked into {leaked}"def test_same_mode_partial_command_rescaffold_keeps_skipped_tracking(self, project_dir, temp_dir@@ -10017,6 +10076,43 @@ class TestPresetSkills:"claude's real ownership must be preserved in the migrated tracking")+ def test_short_and_namespaced_commands_scaffold_consistently(+ self, project_dir, temp_dir+ ):+ """A preset's ``speckit.<cmd>`` and ``speckit.<ns>.<cmd>`` commands must+ scaffold identically in command mode, with no installed extension.++ Regression: the 3-part (``speckit.<ns>.<cmd>``) form was silently+ dropped by a name-shape guard whenever ``.specify/extensions/<ns>/``+ was absent, even though the preset ships the command body itself. The+ 2-part form always scaffolded. Both are self-contained and must behave+ the same (#4076).+ """+ self._write_init_options(project_dir, ai="gemini", ai_skills=False)+ gemini_commands_dir = project_dir / ".gemini" / "commands"+ gemini_commands_dir.mkdir(parents=True)++ short_preset = self._create_command_preset(+ temp_dir, "short-cmd", "speckit.newcmd", "Short", "short body",+ )+ ns_preset = self._create_command_preset(+ temp_dir, "ns-cmd", "speckit.fakeext.newcmd", "Namespaced", "ns body",+ )++ manager = PresetManager(project_dir)+ manager.install_from_directory(short_preset, "0.1.5")+ manager.install_from_directory(ns_preset, "0.1.5")++ short_file = gemini_commands_dir / "speckit.newcmd.toml"+ ns_file = gemini_commands_dir / "speckit.fakeext.newcmd.toml"+ assert short_file.exists(), "2-part command should scaffold"+ assert ns_file.exists(), (+ "3-part namespaced command must scaffold too, even without the "+ "matching extension installed"+ )+ assert manager.registry.get("short-cmd")["registered_commands"] != {}+ assert manager.registry.get("ns-cmd")["registered_commands"] != {}+class TestPresetSetPriority:"""Test preset set-priority CLI command."""