feat: actionable error messages for unsupported Git hosts

- Add unsupported_host_error() function with clear fix instructions
- Show supported hosts list (github.com, *.ghe.com, Azure DevOps)
- Include platform-specific env var examples (Linux/macOS/Windows)
- Display mismatch when GITHUB_HOST is set but different host is used
- Add unit tests for new error message function

Author: danielmeppiel

docs/getting-started.md

@@ -124,7 +124,7 @@ apm install partner.ghe.com/external/integration  # FQDN always works
 apm install github.com/public/open-source-package
 ```
 
-**Key Insight:** Use `GITHUB_HOST` to set your default for bare package names. Use FQDN syntax to explicitly specify any Git host.
+**Key Insight:** Use `GITHUB_HOST` to set your default for bare package names. Use FQDN syntax to specify supported hosts explicitly (e.g., `github.com`, `*.ghe.com`, Azure DevOps). Custom hosts require setting `GITHUB_HOST`.
 
 ### Azure DevOps Support
 

src/apm_cli/models/apm_package.py

@@ -2,7 +2,7 @@
 
 import re
 import urllib.parse
-from ..utils.github_host import is_supported_git_host, is_azure_devops_hostname, default_host
+from ..utils.github_host import is_supported_git_host, is_azure_devops_hostname, default_host, unsupported_host_error
 import yaml
 from dataclasses import dataclass
 from enum import Enum
@@ -305,7 +305,7 @@ def parse(cls, dependency_str: str) -> "DependencyReference":
 
         # SECURITY: Reject protocol-relative URLs (//example.com)
         if dependency_str.startswith('//'):
-            raise ValueError("Unsupported Git host. Protocol-relative URLs are not allowed")
+            raise ValueError(unsupported_host_error("//...", context="Protocol-relative URLs are not supported"))
 
         # Early detection of virtual packages (3+ path segments)
         # Extract the core path before processing reference (#) and alias (@)
@@ -353,14 +353,14 @@ def parse(cls, dependency_str: str) -> "DependencyReference":
                         else:
                             # First segment has a dot but is NOT a valid Git host - REJECT
                             raise ValueError(
-                                f"Unsupported Git host. Invalid hostname: {hostname or first_segment}"
+                                unsupported_host_error(hostname or first_segment)
                             )
                     except (ValueError, AttributeError) as e:
                         # If we can't parse or validate, and first segment has dot, it's suspicious - REJECT
                         if isinstance(e, ValueError) and "Unsupported Git host" in str(e):
                             raise  # Re-raise our security error
                         raise ValueError(
-                            f"Unsupported Git host. Could not validate hostname: {first_segment}"
+                            unsupported_host_error(first_segment)
                         )
                 elif check_str.startswith('gh/'):
                     # Handle 'gh/' shorthand - only if it's exactly at the start
@@ -562,7 +562,7 @@ def parse(cls, dependency_str: str) -> "DependencyReference":
             # Accept github.com, GitHub Enterprise, Azure DevOps, etc. Use parsed_url.hostname
             hostname = parsed_url.hostname or ""
             if not is_supported_git_host(hostname):
-                raise ValueError(f"Unsupported Git host, got hostname: {parsed_url.netloc}")
+                raise ValueError(unsupported_host_error(hostname or parsed_url.netloc))
 
             # Extract and validate the path
             path = parsed_url.path.strip("/")

src/apm_cli/utils/github_host.py

@@ -76,6 +76,49 @@ def is_supported_git_host(hostname: Optional[str]) -> bool:
     return False
 
 
+def unsupported_host_error(hostname: str, context: Optional[str] = None) -> str:
+    """Generate an actionable error message for unsupported Git hosts.
+    
+    Args:
+        hostname: The hostname that was rejected
+        context: Optional context message (e.g., "Protocol-relative URLs are not supported")
+    
+    Returns:
+        str: A user-friendly error message with fix instructions
+    """
+    current_host = os.environ.get("GITHUB_HOST", "")
+    
+    msg = ""
+    if context:
+        msg += f"{context}\n\n"
+    
+    msg += f"Unsupported Git host: '{hostname}'.\n"
+    msg += "\n"
+    msg += "APM only allows these Git hosts by default:\n"
+    msg += "  • github.com\n"
+    msg += "  • *.ghe.com (GitHub Enterprise Cloud)\n"
+    msg += "  • dev.azure.com, *.visualstudio.com (Azure DevOps)\n"
+    msg += "\n"
+    
+    if current_host:
+        msg += f"Your GITHUB_HOST is set to: '{current_host}'\n"
+        msg += f"But you're trying to use: '{hostname}'\n"
+        msg += "\n"
+    
+    msg += f"To use '{hostname}', set the GITHUB_HOST environment variable:\n"
+    msg += "\n"
+    msg += f"  # Linux/macOS:\n"
+    msg += f"  export GITHUB_HOST={hostname}\n"
+    msg += "\n"
+    msg += f"  # Windows (PowerShell):\n"
+    msg += f'  $env:GITHUB_HOST = "{hostname}"\n'
+    msg += "\n"
+    msg += f"  # Windows (Command Prompt):\n"
+    msg += f"  set GITHUB_HOST={hostname}\n"
+    
+    return msg
+
+
 def build_ssh_url(host: str, repo_ref: str) -> str:
     """Build an SSH clone URL for the given host and repo_ref (owner/repo)."""
     return f"git@{host}:{repo_ref}.git"

tests/unit/test_github_host.py

@@ -109,6 +109,37 @@ def test_sanitize_token_url_in_message():
     assert f"***@{host}" in sanitized
 
 
+def test_unsupported_host_error_message():
+    """Test that unsupported host error provides actionable guidance."""
+    error_msg = github_host.unsupported_host_error("github.company.com")
+    
+    # Should mention the hostname
+    assert "github.company.com" in error_msg
+    
+    # Should list supported hosts
+    assert "github.com" in error_msg
+    assert "*.ghe.com" in error_msg
+    assert "dev.azure.com" in error_msg
+    
+    # Should provide fix instructions for all platforms
+    assert "export GITHUB_HOST=" in error_msg
+    assert "$env:GITHUB_HOST" in error_msg
+    assert "set GITHUB_HOST=" in error_msg
+
+
+def test_unsupported_host_error_shows_current_host(monkeypatch):
+    """Test that error shows current GITHUB_HOST if set."""
+    monkeypatch.setenv("GITHUB_HOST", "other.company.com")
+    
+    error_msg = github_host.unsupported_host_error("github.company.com")
+    
+    # Should show the mismatch
+    assert "other.company.com" in error_msg
+    assert "github.company.com" in error_msg
+    
+    monkeypatch.delenv("GITHUB_HOST", raising=False)
+
+
 # Azure DevOps URL builder tests
 
 def test_build_ado_https_clone_url():
@@ -150,3 +181,48 @@ def test_build_ado_api_url():
     assert "path=apm.yml" in url
     assert "versionDescriptor.version=main" in url
     assert "api-version=7.0" in url
+
+
+# Unsupported host error message tests
+
+def test_unsupported_host_error_message():
+    """Test that unsupported host error provides actionable guidance."""
+    error_msg = github_host.unsupported_host_error("github.company.com")
+    
+    # Should mention the hostname
+    assert "github.company.com" in error_msg
+    
+    # Should list supported hosts
+    assert "github.com" in error_msg
+    assert "*.ghe.com" in error_msg
+    assert "dev.azure.com" in error_msg
+    
+    # Should provide fix instructions for all platforms
+    assert "export GITHUB_HOST=" in error_msg
+    assert "$env:GITHUB_HOST" in error_msg
+    assert "set GITHUB_HOST=" in error_msg
+
+
+def test_unsupported_host_error_with_context():
+    """Test that context message is included when provided."""
+    error_msg = github_host.unsupported_host_error("//evil.com", context="Protocol-relative URLs are not supported")
+    
+    # Should include the context
+    assert "Protocol-relative URLs are not supported" in error_msg
+    
+    # Should still include standard guidance
+    assert "github.com" in error_msg
+    assert "GITHUB_HOST" in error_msg
+
+
+def test_unsupported_host_error_shows_current_host(monkeypatch):
+    """Test that error shows current GITHUB_HOST if set."""
+    monkeypatch.setenv("GITHUB_HOST", "other.company.com")
+    
+    error_msg = github_host.unsupported_host_error("github.company.com")
+    
+    # Should show the mismatch
+    assert "other.company.com" in error_msg
+    assert "github.company.com" in error_msg
+    
+    monkeypatch.delenv("GITHUB_HOST", raising=False)