feat(n7web): sync N7 scene cards and optimize runtime

tools/start_n7web.py

@@ -8,6 +8,7 @@ import json
 import os
 import shlex
 import shutil
+import socket
 import subprocess
 import sys
 import time
@@ -183,6 +184,41 @@ def _display_command(command: Sequence[str]) -> str:
     return shlex.join(command)
 
 
+def _probe_host(bind_address: str) -> str:
+    address = str(bind_address).strip()
+    if address in {"", "0.0.0.0"}:
+        return "127.0.0.1"
+    if address == "::":
+        return "::1"
+    return address
+
+
+def _tcp_port_is_listening(bind_address: str, port: int) -> bool:
+    try:
+        with socket.create_connection((_probe_host(bind_address), port), timeout=0.25):
+            return True
+    except OSError:
+        return False
+
+
+def _ensure_service_ports_available(args: argparse.Namespace) -> None:
+    endpoints = (
+        ("main N7Web service", args.host, args.port),
+        ("LAN mode-card service", args.scene_bind, args.scene_port),
+    )
+    occupied = [
+        f"{name} ({_probe_host(host)}:{port})"
+        for name, host, port in endpoints
+        if _tcp_port_is_listening(host, port)
+    ]
+    if occupied:
+        joined = ", ".join(occupied)
+        raise RuntimeError(
+            f"service port already in use: {joined}; stop the previous N7Web "
+            "instance before starting another"
+        )
+
+
 def _resolve_npm() -> Path:
     executable = shutil.which("npm.cmd" if os.name == "nt" else "npm")
     if not executable:
@@ -314,13 +350,13 @@ def run(argv: Sequence[str] | None = None) -> int:
     if args.dry_run:
         return 0
 
-
-    if npm is not None:
-        try:
+    try:
+        _ensure_service_ports_available(args)
+        if npm is not None:
             _build_web_console(npm)
-        except RuntimeError as exc:
-            print(f"startup failed: {exc}", file=sys.stderr, flush=True)
-            return 1
+    except RuntimeError as exc:
+        print(f"startup failed: {exc}", file=sys.stderr, flush=True)
+        return 1
 
     children: list[ChildProcess] = []
     interrupted = False