fix: Add fallback channels when NixOS API discovery fails (#52) (#54)

* fix: Add fallback channels when NixOS API discovery fails (#52)

Resolves issue where users encountered "Invalid channel 'stable'" errors
when the NixOS API was unreachable or slow, leaving channel discovery
with empty results.

Changes:
- Add static FALLBACK_CHANNELS mapping for reliable offline operation
- Increase API timeout from 5s to 10s for slow connections
- Remove deprecated channels (20.09, 24.11 EOL June 2025)
- Add using_fallback flag to ChannelCache
- Display warnings in nixos_channels() when fallback is active
- Update 7 tests to verify fallback behavior
- Ensure all channel-based tools work with fallback channels

The fallback channels provide a safety net while maintaining the
dynamic discovery feature for up-to-date channel information.

* fix(tests): Update NixHub tests to reflect actual API data

Ruby version positions in NixHub API have shifted as new versions
were released. Updated tests to use Ruby 3.0.x (positions 36-42)
instead of Ruby 2.6.7 (position 52), which is beyond the standard
limit=50 upper bound.

Changes:
- test_ai_response_for_missing_version: Use Ruby 3.0 instead of 2.6
- test_efficient_search_strategy: Updated to test Ruby 3.0
- test_finding_older_ruby_version: Use Ruby 3.0 (within limit=50)
- test_version_not_in_nixhub: Remove assertion for 2.6, test 2.7/3.0

These changes ensure tests remain stable as new Ruby versions are
released to NixHub, while still testing the intended behavior of
finding older versions with appropriate limits.

Author: jamesbrink

.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Task",
+      "Glob",
+      "Grep",
+      "LS",
+      "Read",
+      "Edit",
+      "MultiEdit",
+      "Write",
+      "WebFetch",
+      "WebSearch"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "nixos"
+  ]
+}

mcp_nixos/server.py

@@ -38,6 +38,16 @@ class DocumentParseError(Exception):
     "25.05": "nixos-25.05",
 }
 
+# Fallback channels when API discovery fails
+# These are static mappings based on most recent known patterns
+FALLBACK_CHANNELS = {
+    "unstable": "latest-44-nixos-unstable",
+    "stable": "latest-44-nixos-25.05",
+    "25.05": "latest-44-nixos-25.05",
+    "25.11": "latest-44-nixos-25.11",  # For when 25.11 is released
+    "beta": "latest-44-nixos-25.05",
+}
+
 HOME_MANAGER_URL = "https://nix-community.github.io/home-manager/options.xhtml"
 DARWIN_URL = "https://nix-darwin.github.io/nix-darwin/manual/index.html"
 
@@ -49,6 +59,7 @@ def __init__(self) -> None:
         """Initialize empty cache."""
         self.available_channels: dict[str, str] | None = None
         self.resolved_channels: dict[str, str] | None = None
+        self.using_fallback: bool = False
 
     def get_available(self) -> dict[str, str]:
         """Get available channels, discovering if needed."""
@@ -66,7 +77,8 @@ def _discover_available_channels(self) -> dict[str, str]:
         """Discover available NixOS channels by testing API patterns."""
         # Test multiple generation patterns (43, 44, 45) and versions
         generations = [43, 44, 45, 46]  # Future-proof
-        versions = ["unstable", "20.09", "24.11", "25.05", "25.11", "26.05", "30.05"]  # Past, current and future
+        # Removed deprecated versions (20.09, 24.11 - EOL June 2025)
+        versions = ["unstable", "25.05", "25.11", "26.05", "30.05"]  # Current and future
 
         available = {}
         for gen in generations:
@@ -77,7 +89,7 @@ def _discover_available_channels(self) -> dict[str, str]:
                         f"{NIXOS_API}/{pattern}/_count",
                         json={"query": {"match_all": {}}},
                         auth=NIXOS_AUTH,
-                        timeout=5,
+                        timeout=10,  # Increased from 5s to 10s for slow connections
                     )
                     if resp.status_code == 200:
                         count = resp.json().get("count", 0)
@@ -91,6 +103,12 @@ def _discover_available_channels(self) -> dict[str, str]:
     def _resolve_channels(self) -> dict[str, str]:
         """Resolve user-friendly channel names to actual indices."""
         available = self.get_available()
+
+        # If no channels were discovered, use fallback channels
+        if not available:
+            self.using_fallback = True
+            return FALLBACK_CHANNELS.copy()
+
         resolved = {}
 
         # Find unstable (should be consistent)
@@ -140,6 +158,11 @@ def _resolve_channels(self) -> dict[str, str]:
         if "stable" in resolved:
             resolved["beta"] = resolved["stable"]
 
+        # If we still have no channels after all that, use fallback
+        if not resolved:
+            self.using_fallback = True
+            return FALLBACK_CHANNELS.copy()
+
         return resolved
 
 
@@ -523,7 +546,15 @@ async def nixos_channels() -> str:
         available = channel_cache.get_available()
 
         results = []
-        results.append("NixOS Channels (auto-discovered):\n")
+
+        # Show warning if using fallback channels
+        if channel_cache.using_fallback:
+            results.append("⚠️  WARNING: Using fallback channels (API discovery failed)")
+            results.append("    Check network connectivity to search.nixos.org")
+            results.append("")
+            results.append("NixOS Channels (fallback mode):\n")
+        else:
+            results.append("NixOS Channels (auto-discovered):\n")
 
         # Show user-friendly channel names
         for name, index in sorted(configured.items()):
@@ -543,19 +574,26 @@ async def nixos_channels() -> str:
             if index in available:
                 results.append(f"  Status: {status} ({doc_count})")
             else:
-                results.append(f"  Status: {status}")
+                if channel_cache.using_fallback:
+                    results.append("  Status: Fallback (may not be current)")
+                else:
+                    results.append(f"  Status: {status}")
             results.append("")
 
         # Show additional discovered channels not in our mapping
-        discovered_only = set(available.keys()) - set(configured.values())
-        if discovered_only:
-            results.append("Additional available channels:")
-            for index in sorted(discovered_only):
-                results.append(f"• {index} ({available[index]})")
+        if not channel_cache.using_fallback:
+            discovered_only = set(available.keys()) - set(configured.values())
+            if discovered_only:
+                results.append("Additional available channels:")
+                for index in sorted(discovered_only):
+                    results.append(f"• {index} ({available[index]})")
 
         # Add deprecation warnings
         results.append("\nNote: Channels are dynamically discovered.")
         results.append("'stable' always points to the current stable release.")
+        if channel_cache.using_fallback:
+            results.append("\n⚠️  Fallback channels may not reflect the latest available versions.")
+            results.append("   Please check your network connection to search.nixos.org.")
 
         return "\n".join(results).strip()
     except Exception as e: