π« Toolkit to help you get started with SDD or any other process!
fix: unofficial PyPI warning (#1982) and legacy extension command name auto-correction (#2017) (#2027)
Michal Bachorik33a28ec8f7f8
diff --git a/README.md b/README.mdindex a8a8d3a3e..54e245d63 100644--- a/README.md+++ b/README.md@@ -50,6 +50,8 @@ Spec-Driven Development **flips the script** on traditional software developmentChoose your preferred installation method:+> **Important:** The only official, maintained packages for Spec Kit are published from this GitHub repository. Any packages with the same name on PyPI are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. Always install directly from GitHub as shown below.+#### Option 1: Persistent Installation (Recommended)Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):@@ -62,7 +64,13 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vXuv tool install specify-cli --from git+https://github.com/github/spec-kit.git```-Then use the tool directly:+Then verify the correct version is installed:++```bash+specify version+```++And use the tool directly:```bash# Create new projectdiff --git a/docs/installation.md b/docs/installation.mdindex 5d560b6e3..ed253902a 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -10,6 +10,8 @@## Installation+> **Important:** The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.+### Initialize a New ProjectThe easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):@@ -69,6 +71,14 @@ uvx --from git+https://github.com/github/[email protected] specify init <proje## Verification+After installation, run the following command to confirm the correct version is installed:++```bash+specify version+```++This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.+After initialization, you should see the following commands available in your AI agent:- `/speckit.specify` - Create specificationsdiff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex eb4c306bf..b7b0c909a 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -3318,6 +3318,10 @@ def extension_add(console.print("\n[green]β[/green] Extension installed successfully!")console.print(f"\n[bold]{manifest.name}[/bold] (v{manifest.version})")console.print(f" {manifest.description}")++ for warning in manifest.warnings:+ console.print(f"\n[yellow]β Compatibility warning:[/yellow] {warning}")+console.print("\n[bold cyan]Provided commands:[/bold cyan]")for cmd in manifest.commands:console.print(f" β’ {cmd['name']} - {cmd.get('description', '')}")@@ -3371,15 +3375,28 @@ def extension_remove(# Get extension info for command and skill countsext_manifest = manager.get_extension(extension_id)- cmd_count = len(ext_manifest.commands) if ext_manifest else 0reg_meta = manager.registry.get(extension_id)+ # Derive cmd_count from the registry's registered_commands (includes aliases)+ # rather than from the manifest (primary commands only). Use max() across+ # agents to get the per-agent count; sum() would double-count since users+ # think in logical commands, not per-agent file counts.+ # Use get() without a default so we can distinguish "key missing" (fall back+ # to manifest) from "key present but empty dict" (zero commands registered).+ registered_commands = reg_meta.get("registered_commands") if isinstance(reg_meta, dict) else None+ if isinstance(registered_commands, dict):+ cmd_count = max(+ (len(v) for v in registered_commands.values() if isinstance(v, list)),+ default=0,+ )+ else:+ cmd_count = len(ext_manifest.commands) if ext_manifest else 0raw_skills = reg_meta.get("registered_skills") if reg_meta else Noneskill_count = len(raw_skills) if isinstance(raw_skills, list) else 0# Confirm removalif not force:console.print("\n[yellow]β This will remove:[/yellow]")- console.print(f" β’ {cmd_count} commands from AI agent")+ console.print(f" β’ {cmd_count} command{'s' if cmd_count != 1 else ''} per agent")if skill_count:console.print(f" β’ {skill_count} agent skill(s)")console.print(f" β’ Extension directory: .specify/extensions/{extension_id}/")diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex e978d0136..c177e2a27 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -660,6 +660,15 @@ class CommandRegistrar:cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"if cmd_file.exists():cmd_file.unlink()+ # For SKILL.md agents each command lives in its own subdirectory+ # (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). Remove the+ # parent dir when it becomes empty to avoid orphaned directories.+ parent = cmd_file.parent+ if parent != commands_dir and parent.exists():+ try:+ parent.rmdir() # no-op if dir still has other files+ except OSError:+ passif agent_name == "copilot":prompt_file = (diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.pyindex 8f45c425a..852699c39 100644--- a/src/specify_cli/extensions.py+++ b/src/specify_cli/extensions.py@@ -132,6 +132,7 @@ class ExtensionManifest:ValidationError: If manifest is invalid"""self.path = manifest_path+ self.warnings: List[str] = []self.data = self._load_yaml(manifest_path)self._validate()@@ -217,17 +218,98 @@ class ExtensionManifest:f"Hook '{hook_name}' missing required 'command' field")- # Validate commands (if present)+ # Validate commands; track renames so hook references can be rewritten.+ rename_map: Dict[str, str] = {}for cmd in commands:+ if not isinstance(cmd, dict):+ raise ValidationError(+ "Each command entry in 'provides.commands' must be a mapping"+ )if "name" not in cmd or "file" not in cmd:raise ValidationError("Command missing 'name' or 'file'")# Validate command name format- if EXTENSION_COMMAND_NAME_PATTERN.match(cmd["name"]) is None:+ if not EXTENSION_COMMAND_NAME_PATTERN.match(cmd["name"]):+ corrected = self._try_correct_command_name(cmd["name"], ext["id"])+ if corrected:+ self.warnings.append(+ f"Command name '{cmd['name']}' does not follow the required pattern "+ f"'speckit.{{extension}}.{{command}}'. Registering as '{corrected}'. "+ f"The extension author should update the manifest to use this name."+ )+ rename_map[cmd["name"]] = corrected+ cmd["name"] = corrected+ else:+ raise ValidationError(+ f"Invalid command name '{cmd['name']}': "+ "must follow pattern 'speckit.{extension}.{command}'"+ )++ # Validate alias types; no pattern enforcement on aliases β they are+ # intentionally free-form to preserve community extension compatibility+ # (e.g. 'speckit.verify' short aliases used by existing extensions).+ aliases = cmd.get("aliases")+ if aliases is None:+ cmd["aliases"] = []+ aliases = []+ if not isinstance(aliases, list):raise ValidationError(- f"Invalid command name '{cmd['name']}': "- "must follow pattern 'speckit.{extension}.{command}'"+ f"Aliases for command '{cmd['name']}' must be a list")+ for alias in aliases:+ if not isinstance(alias, str):+ raise ValidationError(+ f"Aliases for command '{cmd['name']}' must be strings"+ )++ # Rewrite any hook command references that pointed at a renamed command or+ # an alias-form ref (ext.cmd β speckit.ext.cmd). Always emit a warning when+ # the reference is changed so extension authors know to update the manifest.+ for hook_name, hook_data in self.data.get("hooks", {}).items():+ if not isinstance(hook_data, dict):+ raise ValidationError(+ f"Hook '{hook_name}' must be a mapping, got {type(hook_data).__name__}"+ )+ command_ref = hook_data.get("command")+ if not isinstance(command_ref, str):+ continue+ # Step 1: apply any rename from the auto-correction pass.+ after_rename = rename_map.get(command_ref, command_ref)+ # Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.+ parts = after_rename.split(".")+ if len(parts) == 2 and parts[0] == ext["id"]:+ final_ref = f"speckit.{ext['id']}.{parts[1]}"+ else:+ final_ref = after_rename+ if final_ref != command_ref:+ hook_data["command"] = final_ref+ self.warnings.append(+ f"Hook '{hook_name}' referenced command '{command_ref}'; "+ f"updated to canonical form '{final_ref}'. "+ f"The extension author should update the manifest."+ )++ @staticmethod+ def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:+ """Try to auto-correct a non-conforming command name to the required pattern.++ Handles the two legacy formats used by community extensions:+ - 'speckit.command' β 'speckit.{ext_id}.command'+ - '{ext_id}.command' β 'speckit.{ext_id}.command'++ The 'X.Y' form is only corrected when X matches ext_id to ensure the+ result passes the install-time namespace check. Any other prefix is+ uncorrectable and will produce a ValidationError at the call site.++ Returns the corrected name, or None if no safe correction is possible.+ """+ parts = name.split('.')+ if len(parts) == 2:+ if parts[0] == 'speckit' or parts[0] == ext_id:+ candidate = f"speckit.{ext_id}.{parts[1]}"+ if EXTENSION_COMMAND_NAME_PATTERN.match(candidate):+ return candidate+ return None@propertydef id(self) -> str:diff --git a/tests/test_extensions.py b/tests/test_extensions.pyindex a6ddff8e1..bec939702 100644--- a/tests/test_extensions.py+++ b/tests/test_extensions.py@@ -243,7 +243,7 @@ class TestExtensionManifest:ExtensionManifest(manifest_path)def test_invalid_command_name(self, temp_dir, valid_manifest_data):- """Test manifest with invalid command name format."""+ """Test manifest with command name that cannot be auto-corrected raises ValidationError."""import yamlvalid_manifest_data["provides"]["commands"][0]["name"] = "invalid-name"@@ -255,6 +255,83 @@ class TestExtensionManifest:with pytest.raises(ValidationError, match="Invalid command name"):ExtensionManifest(manifest_path)+ def test_command_name_autocorrect_speckit_prefix(self, temp_dir, valid_manifest_data):+ """Test that 'speckit.command' is auto-corrected to 'speckit.{ext_id}.command'."""+ import yaml++ valid_manifest_data["provides"]["commands"][0]["name"] = "speckit.hello"++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ manifest = ExtensionManifest(manifest_path)++ assert manifest.commands[0]["name"] == "speckit.test-ext.hello"+ assert len(manifest.warnings) == 1+ assert "speckit.hello" in manifest.warnings[0]+ assert "speckit.test-ext.hello" in manifest.warnings[0]++ def test_command_name_autocorrect_matching_ext_id_prefix(self, temp_dir, valid_manifest_data):+ """Test that '{ext_id}.command' is auto-corrected to 'speckit.{ext_id}.command'."""+ import yaml++ # Set ext_id to match the legacy namespace so correction is valid+ valid_manifest_data["extension"]["id"] = "docguard"+ valid_manifest_data["provides"]["commands"][0]["name"] = "docguard.guard"++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ manifest = ExtensionManifest(manifest_path)++ assert manifest.commands[0]["name"] == "speckit.docguard.guard"+ assert len(manifest.warnings) == 1+ assert "docguard.guard" in manifest.warnings[0]+ assert "speckit.docguard.guard" in manifest.warnings[0]++ def test_command_name_mismatched_namespace_not_corrected(self, temp_dir, valid_manifest_data):+ """Test that 'X.command' is NOT corrected when X doesn't match ext_id."""+ import yaml++ # ext_id is "test-ext" but command uses a different namespace+ valid_manifest_data["provides"]["commands"][0]["name"] = "docguard.guard"++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ with pytest.raises(ValidationError, match="Invalid command name"):+ ExtensionManifest(manifest_path)++ def test_alias_free_form_accepted(self, temp_dir, valid_manifest_data):+ """Aliases are free-form β a 'speckit.command' alias must be accepted unchanged."""+ import yaml++ valid_manifest_data["provides"]["commands"][0]["aliases"] = ["speckit.hello"]++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ manifest = ExtensionManifest(manifest_path)++ assert manifest.commands[0]["aliases"] == ["speckit.hello"]+ assert manifest.warnings == []++ def test_valid_command_name_has_no_warnings(self, temp_dir, valid_manifest_data):+ """Test that a correctly-named command produces no warnings."""+ import yaml++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ manifest = ExtensionManifest(manifest_path)++ assert manifest.warnings == []+def test_no_commands_no_hooks(self, temp_dir, valid_manifest_data):"""Test manifest with no commands and no hooks provided."""import yaml@@ -317,6 +394,19 @@ class TestExtensionManifest:with pytest.raises(ValidationError, match="Invalid hooks"):ExtensionManifest(manifest_path)+ def test_non_dict_hook_entry_raises_validation_error(self, temp_dir, valid_manifest_data):+ """Non-mapping hook entries must raise ValidationError, not silently skip."""+ import yaml++ valid_manifest_data["hooks"]["after_tasks"] = "speckit.test-ext.hello"++ manifest_path = temp_dir / "extension.yml"+ with open(manifest_path, 'w') as f:+ yaml.dump(valid_manifest_data, f)++ with pytest.raises(ValidationError, match="Invalid hook 'after_tasks'"):+ ExtensionManifest(manifest_path)+def test_manifest_hash(self, extension_dir):"""Test manifest hash calculation."""manifest_path = extension_dir / "extension.yml"@@ -686,8 +776,8 @@ class TestExtensionManager:with pytest.raises(ValidationError, match="conflicts with core command namespace"):manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)- def test_install_accepts_short_alias(self, temp_dir, project_dir):- """Install should accept legacy short aliases for community extension compat."""+ def test_install_accepts_free_form_alias(self, temp_dir, project_dir):+ """Aliases are free-form β a short 'speckit.shortcut' alias must be preserved unchanged."""import yamlext_dir = temp_dir / "alias-shortcut"@@ -718,8 +808,10 @@ class TestExtensionManager:(ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\n\nBody")manager = ExtensionManager(project_dir)- # Should not raise β short aliases are allowed- manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)+ manifest = manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)++ assert manifest.commands[0]["aliases"] == ["speckit.shortcut"]+ assert manifest.warnings == []def test_install_rejects_namespace_squatting(self, temp_dir, project_dir):"""Install should reject commands and aliases outside the extension namespace."""@@ -1619,6 +1711,54 @@ Then {AGENT_SCRIPT}prompts_dir = project_dir / ".github" / "prompts"assert not prompts_dir.exists()+ def test_unregister_skill_removes_parent_directory(self, project_dir, temp_dir):+ """Unregistering a SKILL.md command should remove the empty parent subdirectory."""+ import yaml++ ext_dir = temp_dir / "cleanup-ext"+ ext_dir.mkdir()+ (ext_dir / "commands").mkdir()++ manifest_data = {+ "schema_version": "1.0",+ "extension": {+ "id": "cleanup-ext",+ "name": "Cleanup Extension",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.cleanup-ext.run",+ "file": "commands/run.md",+ "description": "Run",+ }+ ]+ },+ }+ with open(ext_dir / "extension.yml", "w") as f:+ yaml.dump(manifest_data, f)+ (ext_dir / "commands" / "run.md").write_text("---\ndescription: Run\n---\n\nBody")++ skills_dir = project_dir / ".agents" / "skills"+ skills_dir.mkdir(parents=True)++ registrar = CommandRegistrar()+ from specify_cli.extensions import ExtensionManifest+ manifest = ExtensionManifest(ext_dir / "extension.yml")+ registered = registrar.register_commands_for_agent("codex", manifest, ext_dir, project_dir)++ skill_subdir = skills_dir / "speckit-cleanup-ext-run"+ assert skill_subdir.exists(), "Skill subdirectory should exist after registration"+ assert (skill_subdir / "SKILL.md").exists()++ registrar.unregister_commands({"codex": ["speckit.cleanup-ext.run"]}, project_dir)++ assert not (skill_subdir / "SKILL.md").exists(), "SKILL.md should be removed"+ assert not skill_subdir.exists(), "Empty parent subdirectory should be removed"+# ===== Utility Function Tests =====@@ -3853,3 +3993,58 @@ class TestHookInvocationRendering:assert "Executing: `/<missing command>`" in messageassert "EXECUTE_COMMAND: <missing command>" in messageassert "EXECUTE_COMMAND_INVOCATION: /<missing command>" in message+++class TestExtensionRemoveCLI:+ """CLI tests for `specify extension remove` confirmation prompt wording."""++ def _install_ext(self, project_dir, ext_dir):+ """Install extension and return the manager."""+ manager = ExtensionManager(project_dir)+ manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)+ return manager++ def test_remove_confirmation_singular_command(self, tmp_path, extension_dir):+ """Confirmation prompt should say '1 command' (singular) when one command registered."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app++ project_dir = tmp_path / "project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()++ manager = self._install_ext(project_dir, extension_dir)+ # Inject registered_commands with 1 entry so cmd_count == 1+ manager.registry.update("test-ext", {"registered_commands": {"claude": ["speckit.test-ext.hello"]}})++ runner = CliRunner()+ with patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app, ["extension", "remove", "test-ext"], input="n\n", catch_exceptions=False+ )++ assert "1 command" in result.output+ assert "1 commands" not in result.output++ def test_remove_confirmation_plural_commands(self, tmp_path, extension_dir):+ """Confirmation prompt should say '2 commands' (plural) when two commands registered."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app++ project_dir = tmp_path / "project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()++ manager = self._install_ext(project_dir, extension_dir)+ # Inject registered_commands with 2 entries so cmd_count == 2+ manager.registry.update("test-ext", {"registered_commands": {"claude": ["speckit.test-ext.hello", "speckit.test-ext.run"]}})++ runner = CliRunner()+ with patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app, ["extension", "remove", "test-ext"], input="n\n", catch_exceptions=False+ )++ assert "2 commands" in result.outputdiff --git a/tests/test_presets.py b/tests/test_presets.pyindex 95af7a900..c7383a1f4 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -1175,8 +1175,7 @@ class TestPresetCatalog:"""Test search with cached catalog data."""from unittest.mock import patch- # Only use the default catalog to prevent fetching the community catalog from the network- monkeypatch.setenv("SPECKIT_PRESET_CATALOG_URL", PresetCatalog.DEFAULT_CATALOG_URL)+ monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL", raising=False)catalog = PresetCatalog(project_dir)catalog.cache_dir.mkdir(parents=True, exist_ok=True)