@neoline/hostbridge 1.4.4 → 2.0.1

package/src/server_control_mcp/doctor.py

@@ -0,0 +1,108 @@
+"""Deterministic HostBridge installation diagnostics."""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from . import __version__
+from .config import load_v1_config
+from .runtime import runtime_paths
+
+
+class DoctorClient(Protocol):
+    def hello(self) -> dict[str, object]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticResult:
+    name: str
+    status: str
+    message: str
+    details: dict[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorReport:
+    results: tuple[DiagnosticResult, ...]
+
+    @property
+    def ok(self) -> bool:
+        return all(result.status != "fail" for result in self.results)
+
+
+def collect_diagnostics(
+    config_path: Path | str,
+    *,
+    client: DoctorClient,
+    executable_paths: list[str],
+) -> DoctorReport:
+    results = [
+        _version_diagnostic(),
+        _config_diagnostic(config_path),
+        _runtime_diagnostic(),
+        _daemon_diagnostic(client),
+        _executable_diagnostic(executable_paths),
+    ]
+    return DoctorReport(tuple(results))
+
+
+def _version_diagnostic() -> DiagnosticResult:
+    root = Path(__file__).parents[2]
+    npm = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    pyproject = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    versions = {
+        "runtime": __version__,
+        "npm": npm.get("version"),
+        "python": pyproject.get("project", {}).get("version"),
+    }
+    status = "pass" if len(set(versions.values())) == 1 and __version__ == "2.0.1" else "fail"
+    return DiagnosticResult("version", status, "version sources agree" if status == "pass" else "version drift detected", versions)
+
+
+def _config_diagnostic(config_path: Path | str) -> DiagnosticResult:
+    try:
+        config = load_v1_config(config_path)
+    except (OSError, ValueError) as exc:
+        return DiagnosticResult("config", "fail", str(exc), {"path": str(config_path)})
+    return DiagnosticResult("config", "pass", "schema v1 configuration is valid", {"path": str(config.path), "hosts": len(config.hosts)})
+
+
+def _runtime_diagnostic() -> DiagnosticResult:
+    paths = runtime_paths()
+    try:
+        paths.ensure_directory()
+    except OSError as exc:
+        return DiagnosticResult("runtime", "fail", str(exc), {"directory": str(paths.directory)})
+    mode = paths.directory.stat().st_mode & 0o777
+    status = "pass" if mode == 0o700 else "fail"
+    return DiagnosticResult(
+        "runtime",
+        status,
+        "runtime directory is private" if status == "pass" else "runtime directory must use mode 0700",
+        {"directory": str(paths.directory), "mode": format(mode, "04o")},
+    )
+
+
+def _daemon_diagnostic(client: DoctorClient) -> DiagnosticResult:
+    try:
+        hello = client.hello()
+    except Exception as exc:
+        return DiagnosticResult("daemon", "fail", f"daemon unavailable: {exc}", {})
+    valid = hello.get("service") == "hostbridge" and hello.get("protocol") == 1
+    return DiagnosticResult(
+        "daemon",
+        "pass" if valid else "fail",
+        "daemon protocol v1 is healthy" if valid else "daemon returned an incompatible handshake",
+        dict(hello),
+    )
+
+
+def _executable_diagnostic(paths: list[str]) -> DiagnosticResult:
+    if not paths:
+        return DiagnosticResult("executable", "fail", "hostbridge executable was not found", {"paths": []})
+    return DiagnosticResult("executable", "pass", "hostbridge executable found", {"paths": paths})

package/src/server_control_mcp/hosts.py

@@ -34,11 +34,12 @@ class HostConfig:
     secrets: dict[str, str] = field(default_factory=dict)
     login_steps: list[LoginStep] = field(default_factory=list)
     ready_expect: str | None = None
+    transport: str = "auto"
 
     @classmethod
-    def script(cls, host_id: str, label: str, script: Path | str) -> HostConfig:
+    def script(cls, host_id: str, label: str, script: Path | str, *, transport: str = "auto") -> HostConfig:
         path = Path(script).expanduser()
-        return cls(host_id, label, "/bin/sh", [str(path)], "script", path)
+        return cls(host_id, label, "/bin/sh", [str(path)], "script", path, transport=transport)
 
     @classmethod
     def command_line(
@@ -52,6 +53,7 @@ class HostConfig:
         secrets: dict[str, str] | None = None,
         login_steps: list[LoginStep] | None = None,
         ready_expect: str | None = None,
+        transport: str = "auto",
     ) -> HostConfig:
         return cls(
             host_id,
@@ -63,6 +65,7 @@ class HostConfig:
             secrets or {},
             login_steps or [],
             ready_expect,
+            transport,
         )
 
     def describe(self) -> dict[str, object]:
@@ -72,6 +75,7 @@ class HostConfig:
             "connection_type": self.connection_type,
             "command": self.command,
             "args": list(self.args),
+            "transport": self.transport,
         }
         if self.script_path is not None:
             info.update(
@@ -130,16 +134,40 @@ def _parse_host(item: object, path: Path, index: int) -> HostConfig:
     secrets = _parse_secrets(item.get("secrets", {}), path, index)
     login_steps = _parse_login_steps(item.get("login_steps", []), path, index)
     ready_expect = _parse_ready_expect(item.get("ready_expect"), path, index)
+    transport = str(item.get("transport", "auto")).strip().lower()
+    if transport not in {"auto", "pty", "ssh"}:
+        raise ValueError(f"{path} hosts[{index}].transport must be one of: auto, pty, ssh")
 
     if "script" in item:
         script = str(item.get("script", "")).strip()
         if not script:
             raise ValueError(f"{path} hosts[{index}].script must not be empty")
-        host = HostConfig.script(host_id, label, script)
-        return HostConfig(host.id, host.label, host.command, host.args, host.connection_type, host.script_path, secrets, login_steps, ready_expect)
+        host = HostConfig.script(host_id, label, script, transport=transport)
+        return HostConfig(
+            host.id,
+            host.label,
+            host.command,
+            host.args,
+            host.connection_type,
+            host.script_path,
+            secrets,
+            login_steps,
+            ready_expect,
+            transport,
+        )
 
     if "ssh" in item:
-        return HostConfig.command_line(host_id, label, "ssh", _parse_ssh_args(item["ssh"], path, index), connection_type="ssh", secrets=secrets, login_steps=login_steps, ready_expect=ready_expect)
+        return HostConfig.command_line(
+            host_id,
+            label,
+            "ssh",
+            _parse_ssh_args(item["ssh"], path, index),
+            connection_type="ssh",
+            secrets=secrets,
+            login_steps=login_steps,
+            ready_expect=ready_expect,
+            transport=transport,
+        )
 
     command = str(item.get("command", "")).strip()
     args = item.get("args", [])
@@ -147,7 +175,16 @@ def _parse_host(item: object, path: Path, index: int) -> HostConfig:
         raise ValueError(f"{path} hosts[{index}].command must not be empty")
     if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
         raise ValueError(f"{path} hosts[{index}].args must be a list of strings")
-    return HostConfig.command_line(host_id, label, command, args, secrets=secrets, login_steps=login_steps, ready_expect=ready_expect)
+    return HostConfig.command_line(
+        host_id,
+        label,
+        command,
+        args,
+        secrets=secrets,
+        login_steps=login_steps,
+        ready_expect=ready_expect,
+        transport=transport,
+    )
 
 
 def _parse_ready_expect(raw_ready_expect: object, path: Path, index: int) -> str | None:
@@ -196,7 +233,15 @@ def _parse_ssh_args(raw_ssh: object, path: Path, index: int) -> list[str]:
     args: list[str] = []
     port = raw_ssh.get("port")
     if port not in (None, ""):
-        args.extend(["-p", str(int(port))])
+        if isinstance(port, bool) or not isinstance(port, int | str):
+            raise ValueError(f"{path} hosts[{index}].ssh.port must be an integer")
+        try:
+            parsed_port = int(port)
+        except ValueError as exc:
+            raise ValueError(f"{path} hosts[{index}].ssh.port must be an integer") from exc
+        if not 1 <= parsed_port <= 65535:
+            raise ValueError(f"{path} hosts[{index}].ssh.port must be between 1 and 65535")
+        args.extend(["-p", str(parsed_port)])
     identity_file = str(raw_ssh.get("identity_file", "")).strip()
     if identity_file:
         args.extend(["-i", str(Path(identity_file).expanduser())])