Improve macOS diagnostics and doctor output

Author: zx322582

skills/simulateinput/references/cli-usage.md

@@ -35,8 +35,16 @@ Inspect built-in profiles, MCP tools, and current driver capability.
 
 ```powershell
 python -m simulateinput.cli.main doctor
+python -m simulateinput.cli.main doctor --compact
+python -m simulateinput.cli.main doctor --verbose
 ```
 
+Output modes:
+
+- default: profiles, MCP tool names, and driver diagnostics
+- `--compact`: reduced payload for UI surfaces that mainly need driver state and remediation
+- `--verbose`: default payload plus package version and full MCP tool metadata
+
 ### session start
 
 Create a new session.

src/simulateinput/cli/main.py

@@ -12,6 +12,7 @@
 from simulateinput.mcp.server import MCPServer, list_tools
 from simulateinput.runner.case_runner import load_case, run_case
 
+
 def emit(payload: dict) -> None:
     print(json.dumps(payload, indent=2))
 
@@ -21,7 +22,10 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     subparsers.add_parser("version", help="Print the current package version.")
-    subparsers.add_parser("doctor", help="Show built-in profiles and MCP tool names.")
+    doctor_parser = subparsers.add_parser("doctor", help="Show built-in profiles, driver diagnostics, and MCP tool names.")
+    doctor_mode = doctor_parser.add_mutually_exclusive_group()
+    doctor_mode.add_argument("--compact", action="store_true", help="Emit a reduced payload focused on driver status and remediation.")
+    doctor_mode.add_argument("--verbose", action="store_true", help="Emit expanded driver details plus full MCP tool metadata.")
 
     session_parser = subparsers.add_parser("session", help="Manage automation sessions.")
     session_subparsers = session_parser.add_subparsers(dest="session_command", required=True)
@@ -208,6 +212,32 @@ def resolve_engine(state_root: Path | None) -> AutomationEngine:
     return AutomationEngine(state_root=state_root)
 
 
+def build_doctor_payload(engine: AutomationEngine, compact: bool = False, verbose: bool = False) -> dict:
+    driver = engine.probe_driver()
+    tool_defs = list_tools()
+    if compact:
+        return {
+            "ok": True,
+            "driver": {
+                "available": driver["available"],
+                "platform": driver["platform"],
+                "message": driver["message"],
+                "capabilities": driver["capabilities"],
+                "remediation": driver.get("details", {}).get("remediation", []),
+            },
+        }
+    payload = {
+        "ok": True,
+        "profiles": sorted(BUILTIN_PROFILES),
+        "mcp_tools": [tool.name for tool in tool_defs],
+        "driver": driver,
+    }
+    if verbose:
+        payload["version"] = __version__
+        payload["mcp_tool_details"] = [tool.to_dict() for tool in tool_defs]
+    return payload
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser()
     try:
@@ -219,14 +249,7 @@ def main(argv: list[str] | None = None) -> int:
 
         if args.command == "doctor":
             engine = resolve_engine(None)
-            emit(
-                {
-                    "ok": True,
-                    "profiles": sorted(BUILTIN_PROFILES),
-                    "mcp_tools": [tool.name for tool in list_tools()],
-                    "driver": engine.probe_driver(),
-                }
-            )
+            emit(build_doctor_payload(engine, compact=getattr(args, "compact", False), verbose=getattr(args, "verbose", False)))
             return 0
 
         if args.command == "mcp":

src/simulateinput/core/engine.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 
 from simulateinput.core.errors import DriverNotAvailableError
-from simulateinput.core.models import ActionResult, Artifact, ArtifactKind, ElementInfo, WindowInfo
+from simulateinput.core.models import ActionResult, Artifact, ArtifactKind, ElementInfo, PlatformKind, WindowInfo
 from simulateinput.core.session import SessionStore
 from simulateinput.drivers.registry import create_driver
 
@@ -23,6 +23,7 @@ def probe_driver(self) -> dict:
             "platform": probe.platform.value,
             "message": probe.message,
             "capabilities": probe.capabilities,
+            "details": getattr(probe, "details", {}),
         }
 
     def list_windows(self, session_id: str) -> list[WindowInfo]:
@@ -252,12 +253,56 @@ def execute_click_uia(
         if not matches:
             raise ValueError("uia target not found")
         target = matches[0]
+        self._validate_clickable_uia_target(target)
         window = self._resolve_window(session_id, window_id=target.window_id)
         self._focus_window(window)
         payload = self._build_center_payload(target)
         self.driver.click(payload["absolute"]["x"], payload["absolute"]["y"])
         return ActionResult(ok=True, code="OK", message="click_uia executed", data=payload)
 
+    def _validate_clickable_uia_target(self, target: ElementInfo) -> None:
+        if target.platform != PlatformKind.MACOS:
+            return
+        metadata = target.metadata or {}
+        if not metadata:
+            return
+
+        if metadata.get("visible") is False:
+            raise ValueError("macOS UIA target is not visible")
+        if metadata.get("enabled") is False:
+            raise ValueError("macOS UIA target is disabled")
+        if int(target.bounds.width) <= 0 or int(target.bounds.height) <= 0:
+            raise ValueError("macOS UIA target has no clickable size")
+
+        actions = {
+            str(action).strip().casefold()
+            for action in metadata.get("actions", [])
+            if str(action).strip()
+        }
+        actionable_actions = {
+            "axpress",
+            "axconfirm",
+            "axshowmenu",
+            "axpick",
+            "axopen",
+            "axincrement",
+            "axdecrement",
+        }
+        interactive_roles = {
+            "axbutton",
+            "axcheckbox",
+            "axradiobutton",
+            "axpopbutton",
+            "axmenuitem",
+            "axtextfield",
+            "axsecuretextfield",
+            "axlink",
+            "axdisclosuretriangle",
+        }
+        control_type = (target.control_type or "").casefold()
+        if actions and not (actions & actionable_actions) and control_type not in interactive_roles:
+            raise ValueError("macOS UIA target is not actionable for click_uia")
+
     def preview_click_ocr(
         self,
         session_id: str,

src/simulateinput/core/models.py

@@ -98,6 +98,7 @@ class ElementInfo:
     automation_id: str | None = None
     source: str | None = None
     confidence: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -111,6 +112,7 @@ def to_dict(self) -> dict[str, Any]:
             "automation_id": self.automation_id,
             "source": self.source,
             "confidence": float(self.confidence) if self.confidence is not None else None,
+            "metadata": self.metadata,
         }
 
     @classmethod
@@ -126,6 +128,7 @@ def from_dict(cls, payload: dict[str, Any]) -> "ElementInfo":
             automation_id=payload.get("automation_id"),
             source=payload.get("source"),
             confidence=payload.get("confidence"),
+            metadata=payload.get("metadata", {}),
         )
 
 

src/simulateinput/drivers/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Protocol
+from typing import Any, Protocol
 
 from simulateinput.core.models import PlatformKind
 
@@ -12,6 +12,7 @@ class DriverProbe:
     platform: PlatformKind
     message: str = ""
     capabilities: list[str] = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
 
 
 class PlatformDriver(Protocol):

src/simulateinput/drivers/diagnostics.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RemediationHint:
+    kind: str
+    permission: str
+    reason: str
+    system_settings_path: list[str] = field(default_factory=list)
+    shell_hint: str | None = None
+    copyable_steps: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        if self.shell_hint is None:
+            payload.pop("shell_hint", None)
+        if not self.metadata:
+            payload.pop("metadata", None)
+        return payload
+
+
+def permission_remediation(
+    permission: str,
+    reason: str,
+    system_settings_path: list[str],
+    *,
+    shell_hint: str | None = None,
+    copyable_steps: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return RemediationHint(
+        kind="permission",
+        permission=permission,
+        reason=reason,
+        system_settings_path=system_settings_path,
+        shell_hint=shell_hint,
+        copyable_steps=copyable_steps or [],
+        metadata=metadata or {},
+    ).to_dict()