fix(tests): fix 4 failing tests and normalize null aliases in manifest validation (#2017)

- Remove accidental hook reference from alias auto-correction test (fixture
  has after_tasks hook whose command matches the alias being renamed, causing
  a spurious second warning)
- Update collision test fixture to use a primary command collision instead of
  an alias-based one (alias namespace enforcement now makes cross-extension
  alias collisions impossible by design)
- Update test_command_with_aliases and test_copilot_aliases_get_companion_prompts
  to use the new 2-part alias format (ext-id.command) rather than the legacy
  3-part speckit.ext.command form
- Normalize aliases: null to aliases: [] in _validate() so downstream
  cmd_info.get('aliases', []) cannot return None when the YAML key exists
  but is explicitly null

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: iamaeroplane

src/specify_cli/extensions.py

@@ -37,6 +37,9 @@
     "taskstoissues",
 })
 EXTENSION_COMMAND_NAME_PATTERN = re.compile(r"^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$")
+# Aliases use a 2-part 'namespace.command' form without the 'speckit.' prefix.
+# The 'speckit' namespace is reserved for core commands.
+EXTENSION_ALIAS_PATTERN = re.compile(r"^([a-z0-9-]+)\.([a-z0-9-]+)$")
 
 
 def _load_core_command_names() -> frozenset[str]:
@@ -214,6 +217,7 @@ def _validate(self):
             aliases = cmd.get("aliases")
             if aliases is None:
                 aliases = []
+                cmd["aliases"] = []  # normalize null/missing to empty list in-place
             if not isinstance(aliases, list):
                 raise ValidationError(
                     f"Aliases for command '{cmd['name']}' must be a list"
@@ -223,20 +227,24 @@ def _validate(self):
                     raise ValidationError(
                         f"Aliases for command '{cmd['name']}' must be strings"
                     )
-                if not EXTENSION_COMMAND_NAME_PATTERN.match(alias):
-                    corrected = self._try_correct_command_name(alias, ext["id"])
+                alias_match = EXTENSION_ALIAS_PATTERN.match(alias)
+                if alias_match and alias_match.group(1) != 'speckit':
+                    pass  # already valid: 'myext.command' form
+                else:
+                    corrected = self._try_correct_alias_name(alias, ext["id"])
                     if corrected:
                         self.warnings.append(
                             f"Alias '{alias}' does not follow the required pattern "
-                            f"'speckit.{{extension}}.{{command}}'. Registering as '{corrected}'. "
+                            f"'{{extension}}.{{command}}'. Registering as '{corrected}'. "
                             f"The extension author should update the manifest to use this name."
                         )
                         rename_map[alias] = corrected
                         aliases[i] = corrected
                     else:
                         raise ValidationError(
                             f"Invalid alias '{alias}': "
-                            "must follow pattern 'speckit.{extension}.{command}'"
+                            "must follow pattern '{extension}.{command}' "
+                            "(the 'speckit.' prefix is reserved for core commands)"
                         )
 
         # Rewrite any hook command references that pointed at a renamed command.
@@ -252,15 +260,14 @@ def _validate(self):
 
     @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.
+        """Try to auto-correct a non-conforming primary command name to 'speckit.{ext_id}.command'.
 
-        Handles the two legacy formats used by community extensions:
+        Handles legacy formats:
           - '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.
+        result passes the install-time namespace check.
 
         Returns the corrected name, or None if no safe correction is possible.
         """
@@ -272,6 +279,27 @@ def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
                     return candidate
         return None
 
+    @staticmethod
+    def _try_correct_alias_name(name: str, ext_id: str) -> Optional[str]:
+        """Try to auto-correct a non-conforming alias to the '{ext_id}.command' pattern.
+
+        Handles legacy formats:
+          - 'speckit.command'         → '{ext_id}.command'
+          - 'speckit.ext_id.command'  → 'ext_id.command'  (3-part with speckit prefix)
+
+        Returns the corrected name, or None if no safe correction is possible.
+        """
+        parts = name.split('.')
+        if len(parts) == 2 and parts[0] == 'speckit':
+            candidate = f"{ext_id}.{parts[1]}"
+            if EXTENSION_ALIAS_PATTERN.match(candidate):
+                return candidate
+        if len(parts) == 3 and parts[0] == 'speckit':
+            candidate = f"{parts[1]}.{parts[2]}"
+            if EXTENSION_ALIAS_PATTERN.match(candidate):
+                return candidate
+        return None
+
     @property
     def id(self) -> str:
         """Get extension ID."""
@@ -608,14 +636,24 @@ def _collect_manifest_command_names(manifest: ExtensionManifest) -> Dict[str, st
                         f"{kind.capitalize()} for command '{primary_name}' must be a string"
                     )
 
-                match = EXTENSION_COMMAND_NAME_PATTERN.match(name)
-                if match is None:
-                    raise ValidationError(
-                        f"Invalid {kind} '{name}': "
-                        "must follow pattern 'speckit.{extension}.{command}'"
-                    )
+                if kind == "command":
+                    match = EXTENSION_COMMAND_NAME_PATTERN.match(name)
+                    if match is None:
+                        raise ValidationError(
+                            f"Invalid command '{name}': "
+                            "must follow pattern 'speckit.{extension}.{command}'"
+                        )
+                    namespace = match.group(1)
+                else:
+                    match = EXTENSION_ALIAS_PATTERN.match(name)
+                    if match is None or match.group(1) == 'speckit':
+                        raise ValidationError(
+                            f"Invalid alias '{name}': "
+                            "must follow pattern '{extension}.{command}' "
+                            "(the 'speckit.' prefix is reserved for core commands)"
+                        )
+                    namespace = match.group(1)
 
-                namespace = match.group(1)
                 if namespace != manifest.id:
                     raise ValidationError(
                         f"{kind.capitalize()} '{name}' must use extension namespace '{manifest.id}'"

tests/test_extensions.py

@@ -303,8 +303,23 @@ def test_command_name_mismatched_namespace_not_corrected(self, temp_dir, valid_m
         with pytest.raises(ValidationError, match="Invalid command name"):
             ExtensionManifest(manifest_path)
 
-    def test_alias_autocorrect_speckit_prefix(self, temp_dir, valid_manifest_data):
-        """Test that a legacy 'speckit.command' alias is auto-corrected."""
+    def test_alias_valid_two_part_no_prefix(self, temp_dir, valid_manifest_data):
+        """Test that a 'myext.command' alias is accepted as-is with no warning."""
+        import yaml
+
+        valid_manifest_data["provides"]["commands"][0]["aliases"] = ["test-ext.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"] == ["test-ext.hello"]
+        assert manifest.warnings == []
+
+    def test_alias_autocorrect_speckit_two_part(self, temp_dir, valid_manifest_data):
+        """Test that legacy 'speckit.command' alias is corrected to '{ext_id}.command'."""
         import yaml
 
         valid_manifest_data["provides"]["commands"][0]["aliases"] = ["speckit.hello"]
@@ -315,10 +330,29 @@ def test_alias_autocorrect_speckit_prefix(self, temp_dir, valid_manifest_data):
 
         manifest = ExtensionManifest(manifest_path)
 
-        assert manifest.commands[0]["aliases"] == ["speckit.test-ext.hello"]
+        assert manifest.commands[0]["aliases"] == ["test-ext.hello"]
         assert len(manifest.warnings) == 1
         assert "speckit.hello" in manifest.warnings[0]
+        assert "test-ext.hello" in manifest.warnings[0]
+
+    def test_alias_autocorrect_speckit_three_part(self, temp_dir, valid_manifest_data):
+        """Test that a 3-part 'speckit.ext.command' alias is corrected to 'ext.command'."""
+        import yaml
+
+        # Clear hooks so the alias rename doesn't also trigger a hook-reference warning.
+        valid_manifest_data.pop("hooks", None)
+        valid_manifest_data["provides"]["commands"][0]["aliases"] = ["speckit.test-ext.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"] == ["test-ext.hello"]
+        assert len(manifest.warnings) == 1
         assert "speckit.test-ext.hello" in manifest.warnings[0]
+        assert "test-ext.hello" in manifest.warnings[0]
 
     def test_valid_command_name_has_no_warnings(self, temp_dir, valid_manifest_data):
         """Test that a correctly-named command produces no warnings."""
@@ -714,8 +748,8 @@ def test_install_rejects_extension_id_in_core_namespace(self, temp_dir, project_
         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_autocorrects_alias_without_extension_namespace(self, temp_dir, project_dir):
-        """Legacy short aliases are auto-corrected to 'speckit.{ext_id}.{cmd}' with a warning."""
+    def test_install_autocorrects_speckit_alias_to_ext_form(self, temp_dir, project_dir):
+        """Legacy 'speckit.command' aliases are corrected to '{ext_id}.command' with a warning."""
         import yaml
 
         ext_dir = temp_dir / "alias-shortcut"
@@ -748,10 +782,10 @@ def test_install_autocorrects_alias_without_extension_namespace(self, temp_dir,
         manager = ExtensionManager(project_dir)
         manifest = manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
 
-        assert manifest.commands[0]["aliases"] == ["speckit.alias-shortcut.shortcut"]
+        assert manifest.commands[0]["aliases"] == ["alias-shortcut.shortcut"]
         assert len(manifest.warnings) == 1
         assert "speckit.shortcut" in manifest.warnings[0]
-        assert "speckit.alias-shortcut.shortcut" in manifest.warnings[0]
+        assert "alias-shortcut.shortcut" in manifest.warnings[0]
 
     def test_install_rejects_namespace_squatting(self, temp_dir, project_dir):
         """Install should reject commands and aliases outside the extension namespace."""
@@ -789,12 +823,21 @@ def test_install_rejects_namespace_squatting(self, temp_dir, project_dir):
             manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
 
     def test_install_rejects_command_collision_with_installed_extension(self, temp_dir, project_dir):
-        """Install should reject names already claimed by an installed legacy extension."""
+        """Install should reject names already claimed by an installed extension.
+
+        The first extension is written directly to disk (bypassing install_from_directory) to
+        simulate a scenario where it claims a command in a different namespace — something that
+        could happen with a legacy or manually-placed extension.  The collision detector must
+        still catch the conflict when the second extension tries to register the same command.
+        """
         import yaml
 
         first_dir = temp_dir / "ext-one"
         first_dir.mkdir()
         (first_dir / "commands").mkdir()
+        # Directly write a manifest that claims speckit.shared.sync even though its id is
+        # "ext-one" — this bypasses install-time namespace enforcement and simulates a
+        # legacy/corrupted extension that already occupies the name.
         first_manifest = {
             "schema_version": "1.0",
             "extension": {
@@ -807,9 +850,8 @@ def test_install_rejects_command_collision_with_installed_extension(self, temp_d
             "provides": {
                 "commands": [
                     {
-                        "name": "speckit.ext-one.sync",
+                        "name": "speckit.shared.sync",
                         "file": "commands/cmd.md",
-                        "aliases": ["speckit.shared.sync"],
                     }
                 ]
             },
@@ -1148,7 +1190,7 @@ def test_command_with_aliases(self, project_dir, temp_dir):
                     {
                         "name": "speckit.ext-alias.cmd",
                         "file": "commands/cmd.md",
-                        "aliases": ["speckit.ext-alias.shortcut"],
+                        "aliases": ["ext-alias.shortcut"],
                     }
                 ]
             },
@@ -1169,9 +1211,9 @@ def test_command_with_aliases(self, project_dir, temp_dir):
 
         assert len(registered) == 2
         assert "speckit.ext-alias.cmd" in registered
-        assert "speckit.ext-alias.shortcut" in registered
+        assert "ext-alias.shortcut" in registered
         assert (claude_dir / "speckit.ext-alias.cmd.md").exists()
-        assert (claude_dir / "speckit.ext-alias.shortcut.md").exists()
+        assert (claude_dir / "ext-alias.shortcut.md").exists()
 
     def test_unregister_commands_for_codex_skills_uses_mapped_names(self, project_dir):
         """Codex skill cleanup should use the same mapped names as registration."""
@@ -1591,7 +1633,7 @@ def test_copilot_aliases_get_companion_prompts(self, project_dir, temp_dir):
                     {
                         "name": "speckit.ext-alias-copilot.cmd",
                         "file": "commands/cmd.md",
-                        "aliases": ["speckit.ext-alias-copilot.shortcut"],
+                        "aliases": ["ext-alias-copilot.shortcut"],
                     }
                 ]
             },
@@ -1619,7 +1661,7 @@ def test_copilot_aliases_get_companion_prompts(self, project_dir, temp_dir):
         # Both primary and alias get companion .prompt.md
         prompts_dir = project_dir / ".github" / "prompts"
         assert (prompts_dir / "speckit.ext-alias-copilot.cmd.prompt.md").exists()
-        assert (prompts_dir / "speckit.ext-alias-copilot.shortcut.prompt.md").exists()
+        assert (prompts_dir / "ext-alias-copilot.shortcut.prompt.md").exists()
 
     def test_non_copilot_agent_no_companion_file(self, extension_dir, project_dir):
         """Test that non-copilot agents do NOT create .prompt.md files."""