fix(cli): warn when serve --host uses broadcast or special addresses

Fixes bounty issue #1632

Add validation for the --host argument in the serve command to warn users
when they specify problematic IP addresses such as broadcast addresses
(255.255.255.255), multicast addresses (224.0.0.0 - 239.255.255.255),
or documentation addresses. These addresses cannot be properly bound
and would result in confusing errors.

Author: factorydroid

cortex-cli/src/main.rs

@@ -820,9 +820,58 @@ async fn list_features() -> Result<()> {
     Ok(())
 }
 
+/// Check if an IP address is a special address that may cause issues when binding.
+/// Returns Some(warning_message) if the address is problematic, None otherwise.
+fn check_special_ip_address(host: &str) -> Option<&'static str> {
+    use std::net::IpAddr;
+
+    let ip: IpAddr = match host.parse() {
+        Ok(ip) => ip,
+        Err(_) => return None, // Not a valid IP, could be a hostname - let the server handle it
+    };
+
+    match ip {
+        IpAddr::V4(ipv4) => {
+            // Broadcast address
+            if ipv4.is_broadcast() {
+                return Some(
+                    "Warning: 255.255.255.255 is the broadcast address and cannot be used for binding a server.",
+                );
+            }
+            // Multicast addresses (224.0.0.0 - 239.255.255.255)
+            if ipv4.is_multicast() {
+                return Some(
+                    "Warning: Multicast addresses (224.0.0.0 - 239.255.255.255) are not suitable for binding a server.",
+                );
+            }
+            // Documentation addresses (reserved for documentation, not routable)
+            if ipv4.is_documentation() {
+                return Some(
+                    "Warning: Documentation addresses (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24) are reserved and may not work as expected.",
+                );
+            }
+        }
+        IpAddr::V6(ipv6) => {
+            // Multicast addresses
+            if ipv6.is_multicast() {
+                return Some(
+                    "Warning: IPv6 multicast addresses are not suitable for binding a server.",
+                );
+            }
+        }
+    }
+
+    None
+}
+
 async fn run_serve(serve_cli: ServeCommand) -> Result<()> {
     use cortex_engine::MdnsService;
 
+    // Validate the host address and warn about special addresses
+    if let Some(warning) = check_special_ip_address(&serve_cli.host) {
+        eprintln!("{}", warning);
+    }
+
     let config = cortex_app_server::ServerConfig {
         listen_addr: format!("{}:{}", serve_cli.host, serve_cli.port),
         ..Default::default()