update

backend/router_dependency.py

@@ -0,0 +1,77 @@
+# -----------------------------------------------------------------------------
+# Description: Build-time mxpic_router runtime dependency validation helpers.
+# Inside functions: ensure_router_path, require_router_stack
+# Developer : Qin Yue @ 2026
+# Organization : OptiHK Limited
+# -----------------------------------------------------------------------------
+import importlib
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class RouterStackStatus:
+    """Summary of the router stack checks completed for a build action."""
+
+    ok: bool
+    router_root: str
+    checked: List[str] = field(default_factory=list)
+
+
+class RouterStackUnavailable(RuntimeError):
+    """Raised when a build action needs the external router stack but it is absent."""
+    pass
+
+
+def ensure_router_path() -> str:
+    """Add the sibling mxpic_router checkout to import resolution when present."""
+    router_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "mxpic_router"))
+    if os.path.isdir(router_root) and router_root not in sys.path:
+        sys.path.insert(0, router_root)
+    return router_root
+
+
+def require_router_stack(require_gdstk: bool = False) -> RouterStackStatus:
+    """Validate the runtime stack required for build-time router actions."""
+    router_root = ensure_router_path()
+    checked = []
+    missing = []
+
+    try:
+        importlib.import_module("mxpic_router")
+        checked.append("mxpic_router")
+    except Exception as exc:
+        missing.append(f"mxpic_router: {exc}")
+
+    try:
+        importlib.import_module("nazca")
+        checked.append("nazca")
+    except Exception as exc:
+        missing.append(f"nazca: {exc}")
+
+    if require_gdstk:
+        try:
+            importlib.import_module("gdstk")
+            checked.append("gdstk")
+        except Exception as exc:
+            missing.append(f"gdstk: {exc}")
+
+    try:
+        router_builder = importlib.import_module("mxpic_router.builder")
+        route_factory = getattr(router_builder, "_import_mxpic_forge_route")
+        route_factory()
+        checked.append("mxpic_forge Route")
+    except Exception as exc:
+        missing.append(f"mxpic_forge Route: {exc}")
+
+    if missing:
+        details = "; ".join(missing)
+        raise RouterStackUnavailable(
+            "Required mxpic_router runtime stack is unavailable. "
+            "Build actions require the matched mxpic_router and mxpic_forge checkouts, "
+            f"Nazca, and gdstk for SVG preview generation. Details: {details}"
+        )
+
+    return RouterStackStatus(ok=True, router_root=router_root, checked=checked)