refactor: comprehensive code review fixes across 31 files

Addresses all critical, high, medium, and low issues from full codebase
review. 494 tests pass, ruff clean, ty type-check clean.

Security:
- Add tool_error_handler context manager (exceptions.py) — standardised
  error handling, eliminates 11 bare except-reraise patterns
- Remove unused exception subclasses (ConfigurationError, UnraidAPIError,
  SubscriptionError, ValidationError, IdempotentOperationError)
- Harden GraphQL subscription query validator with allow-list and
  forbidden-keyword regex (diagnostics.py)
- Add input validation for rclone create_remote config_data: injection,
  path-traversal, and key-count limits (rclone.py)
- Validate notifications importance enum before GraphQL request (notifications.py)
- Sanitise HTTP/network/JSON error messages — no raw exception strings
  leaked to clients (client.py)
- Strip path/creds from displayed API URL via _safe_display_url (health.py)
- Enable Ruff S (bandit) rule category in pyproject.toml
- Harden container mutations to strict-only matching — no fuzzy/substring
  for destructive operations (docker.py)

Performance:
- Token-bucket rate limiter (90 tokens, 9 req/s) with 429 retry backoff (client.py)
- Lazy asyncio.Lock init via _get_client_lock() — fixes event-loop
  module-load crash (client.py)
- Double-checked locking in get_http_client() for fast-path (client.py)
- Short hex container ID fast-path skips list fetch (docker.py)
- Cap resource_data log content to 1 MB / 5,000 lines (manager.py)
- Reset reconnect counter after 30 s stable connection (manager.py)
- Move tail_lines validation to module level; enforce 10,000 line cap
  (storage.py, docker.py)
- force_terminal=True removed from logging RichHandler (logging.py)

Architecture:
- Register diagnostic tools in server startup (server.py)
- Move ALL_ACTIONS computation to module level in all tools
- Consolidate format_kb / format_bytes into shared core/utils.py
- Add _safe_get() helper in core/utils.py for nested dict traversal
- Extract _analyze_subscription_status() from health.py diagnose handler
- Validate required config at startup — fail fast with CRITICAL log (server.py)

Code quality:
- Remove ~90 lines of dead Rich formatting helpers from logging.py
- Remove dead self.websocket attribute from SubscriptionManager
- Remove dead setup_uvicorn_logging() wrapper
- Move _VALID_IMPORTANCE to module level (N806 fix)
- Add slots=True to all three dataclasses (SubscriptionData, SystemHealth, APIResponse)
- Fix None rendering as literal "None" string in info.py summaries
- Change fuzzy-match log messages from INFO to DEBUG (docker.py)
- UTC-aware datetimes throughout (manager.py, diagnostics.py)

Infrastructure:
- Upgrade base image python:3.11-slim → python:3.12-slim (Dockerfile)
- Add non-root appuser (UID/GID 1000) with HEALTHCHECK (Dockerfile)
- Add read_only, cap_drop: ALL, tmpfs /tmp to docker-compose.yml
- Single-source version via importlib.metadata (pyproject.toml → __init__.py)
- Add open_timeout to all websockets.connect() calls

Tests:
- Update error message matchers to match sanitised messages (test_client.py)
- Fix patch targets for UNRAID_API_URL → utils module (test_subscriptions.py)
- Fix importance="info" → importance="normal" (test_notifications.py, http_layer)
- Fix naive datetime fixtures → UTC-aware (test_subscriptions.py)

Co-authored-by: Claude <claude@anthropic.com>

unraid_mcp/tools/virtualization.py

@@ -10,7 +10,7 @@ from fastmcp import FastMCP
 
 from ..config.logging import logger
 from ..core.client import make_graphql_request
-from ..core.exceptions import ToolError
+from ..core.exceptions import ToolError, tool_error_handler
 
 
 QUERIES: dict[str, str] = {
@@ -19,6 +19,13 @@ QUERIES: dict[str, str] = {
           vms { id domains { id name state uuid } }
         }
     """,
+    # NOTE: The Unraid GraphQL API does not expose a single-VM query.
+    # The details query is identical to list; client-side filtering is required.
+    "details": """
+        query ListVMs {
+          vms { id domains { id name state uuid } }
+        }
+    """,
 }
 
 MUTATIONS: dict[str, str] = {
@@ -64,7 +71,7 @@ VM_ACTIONS = Literal[
     "reset",
 ]
 
-ALL_ACTIONS = set(QUERIES) | set(MUTATIONS) | {"details"}
+ALL_ACTIONS = set(QUERIES) | set(MUTATIONS)
 
 
 def register_vm_tool(mcp: FastMCP) -> None:
@@ -98,20 +105,26 @@ def register_vm_tool(mcp: FastMCP) -> None:
         if action in DESTRUCTIVE_ACTIONS and not confirm:
             raise ToolError(f"Action '{action}' is destructive. Set confirm=True to proceed.")
 
-        try:
-            logger.info(f"Executing unraid_vm action={action}")
+        with tool_error_handler("vm", action, logger):
+            try:
+                logger.info(f"Executing unraid_vm action={action}")
 
-            if action in ("list", "details"):
-                data = await make_graphql_request(QUERIES["list"])
-                if data.get("vms"):
+                if action == "list":
+                    data = await make_graphql_request(QUERIES["list"])
+                    if data.get("vms"):
+                        vms = data["vms"].get("domains") or data["vms"].get("domain") or []
+                        if isinstance(vms, dict):
+                            vms = [vms]
+                        return {"vms": vms}
+                    return {"vms": []}
+
+                if action == "details":
+                    data = await make_graphql_request(QUERIES["details"])
+                    if not data.get("vms"):
+                        raise ToolError("No VM data returned from server")
                     vms = data["vms"].get("domains") or data["vms"].get("domain") or []
                     if isinstance(vms, dict):
                         vms = [vms]
-
-                    if action == "list":
-                        return {"vms": vms}
-
-                    # details: find specific VM
                     for vm in vms:
                         if (
                             vm.get("uuid") == vm_id
@@ -121,33 +134,28 @@ def register_vm_tool(mcp: FastMCP) -> None:
                             return dict(vm)
                     available = [f"{v.get('name')} (UUID: {v.get('uuid')})" for v in vms]
                     raise ToolError(f"VM '{vm_id}' not found. Available: {', '.join(available)}")
-                if action == "details":
-                    raise ToolError("No VM data returned from server")
-                return {"vms": []}
 
-            # Mutations
-            if action in MUTATIONS:
-                data = await make_graphql_request(MUTATIONS[action], {"id": vm_id})
-                field = _MUTATION_FIELDS.get(action, action)
-                if data.get("vm") and field in data["vm"]:
-                    return {
-                        "success": data["vm"][field],
-                        "action": action,
-                        "vm_id": vm_id,
-                    }
-                raise ToolError(f"Failed to {action} VM or unexpected response")
+                # Mutations
+                if action in MUTATIONS:
+                    data = await make_graphql_request(MUTATIONS[action], {"id": vm_id})
+                    field = _MUTATION_FIELDS.get(action, action)
+                    if data.get("vm") and field in data["vm"]:
+                        return {
+                            "success": data["vm"][field],
+                            "action": action,
+                            "vm_id": vm_id,
+                        }
+                    raise ToolError(f"Failed to {action} VM or unexpected response")
 
-            raise ToolError(f"Unhandled action '{action}' — this is a bug")
+                raise ToolError(f"Unhandled action '{action}' — this is a bug")
 
-        except ToolError:
-            raise
-        except Exception as e:
-            logger.error(f"Error in unraid_vm action={action}: {e}", exc_info=True)
-            msg = str(e)
-            if "VMs are not available" in msg:
-                raise ToolError(
-                    "VMs not available on this server. Check VM support is enabled."
-                ) from e
-            raise ToolError(f"Failed to execute vm/{action}: {msg}") from e
+            except ToolError:
+                raise
+            except Exception as e:
+                if "VMs are not available" in str(e):
+                    raise ToolError(
+                        "VMs not available on this server. Check VM support is enabled."
+                    ) from e
+                raise
 
     logger.info("VM tool registered successfully")