VirtualDesktop 1.0.1__py3-none-any.whl

VirtualDesktop/cli.py

@@ -0,0 +1,673 @@
+"""``VirtualDesktop`` command line interface.
+
+Exit codes are stable so that scripts and CI jobs can branch on them (see
+:data:`VirtualDesktop.errors.EXIT_CODES`).
+
+::
+
+    VirtualDesktop check                     # read-only environment report
+    VirtualDesktop install-driver --dry-run  # print exactly what would be executed
+    VirtualDesktop install-driver            # install (raises one UAC prompt)
+    VirtualDesktop uninstall-driver
+    VirtualDesktop list-windows              # find the exact title to target
+    VirtualDesktop mount "Notepad" --out shot.png
+    VirtualDesktop capture "Notepad" --out shot.png --unmount
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from . import __version__
+from ._log import enable_debug_logging
+from ._process import helper_command, run_command
+from ._winapi import IS_WINDOWS, enumerate_monitors, is_admin, list_windows
+from .config import DriverConfig, SessionConfig
+from .driver import DriverInstaller, install_from_helper
+from .errors import EXIT_CODES, OffscreenMountError, WindowNotFoundError
+from .session import OffscreenSession, probe_environment
+from .window import find_window
+
+__all__ = ["main", "build_parser"]
+
+_INTERNAL = "_elevated-install"
+
+
+def _print(payload: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True, default=str))
+        return
+    if isinstance(payload, str):
+        print(payload)
+    else:
+        print(json.dumps(payload, indent=2, sort_keys=True, default=str))
+
+
+def _exit_code_for(exc: Exception) -> int:
+    code = getattr(exc, "code", "")
+    if code == "driver-not-found":
+        return EXIT_CODES["driver-missing"]
+    if code in ("elevation-required", "elevation-denied"):
+        return EXIT_CODES["elevation-required"]
+    if code in ("window-not-found", "window-ambiguous"):
+        return EXIT_CODES["window-not-found"]
+    if code and str(code).startswith("capture"):
+        return EXIT_CODES["capture-failed"]
+    if code == "unsupported-platform":
+        return EXIT_CODES["unsupported-platform"]
+    return EXIT_CODES["error"]
+
+
+def _configure_console() -> None:
+    """Make console output survivable.
+
+    Two Windows-specific hazards this neutralises:
+
+    * a legacy code page (cp936, cp1252, ...) that cannot encode CJK/emoji window titles
+      would raise ``UnicodeEncodeError`` mid-report;
+    * the console disappearing (piped through ``head``, or a closed window) turns the next
+      ``print`` into ``BrokenPipeError``.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (ValueError, OSError):  # pragma: no cover - very old/odd streams
+            pass
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="VirtualDesktop",
+        description="Mount a window on a virtual display, capture it, and put it back.",
+    )
+    parser.add_argument("--version", action="version", version=f"VirtualDesktop {__version__}")
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    parser.add_argument("--debug", action="store_true", help="verbose library logging")
+    parser.add_argument(
+        "--log-file", help="also append logs to this file (rotating, 1 MB x 2)"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # -- check ----------------------------------------------------------------------
+    check = sub.add_parser("check", help="read-only environment and driver report")
+    check.add_argument("--window", type=int, help="also report on this HWND")
+    check.add_argument("--capture-probe", action="store_true", help="try every capture method")
+
+    # -- driver ---------------------------------------------------------------------
+    for name, help_text in (
+        ("install-driver", "download, verify and install the virtual display driver"),
+        ("uninstall-driver", "remove the virtual display device (and optionally the files)"),
+    ):
+        sub_parser = sub.add_parser(name, help=help_text)
+        sub_parser.add_argument("--driver", help="manifest driver key (default: manifest default)")
+        sub_parser.add_argument(
+            "--strategy",
+            default="auto",
+            choices=["auto", "nefcon", "nefcon-manual", "pnputil", "scoop"],
+        )
+        sub_parser.add_argument(
+            "--signature-policy", default="warn", choices=["warn", "strict", "off"]
+        )
+        sub_parser.add_argument("--cache-dir", help="override the artifact cache directory")
+        sub_parser.add_argument("--timeout", type=float, default=600.0)
+        if name == "install-driver":
+            sub_parser.add_argument(
+                "--dry-run",
+                action="store_true",
+                help="verify downloads and print the privileged command without installing",
+            )
+        else:
+            sub_parser.add_argument("--purge-files", action="store_true", help="delete cached driver files")
+            sub_parser.add_argument(
+                "--purge-driver-store", action="store_true", help="also purge the driver store package"
+            )
+    fetch = sub.add_parser("fetch-driver", help="download and verify driver artifacts only")
+    fetch.add_argument("--driver")
+    fetch.add_argument("--cache-dir")
+
+    # -- windows --------------------------------------------------------------------
+    listing = sub.add_parser("list-windows", help="list top-level windows for targeting")
+    listing.add_argument("--all", action="store_true", help="include hidden and tool windows")
+    listing.add_argument("--filter", help="only titles containing this substring")
+
+    # -- mount / capture ------------------------------------------------------------
+    for name in ("mount", "capture"):
+        sub_parser = sub.add_parser(name, help=f"{name} a window on the virtual display")
+        sub_parser.add_argument("title", nargs="?", help="window title (exact, substring or regex)")
+        sub_parser.add_argument("--class", dest="window_class", help="window class name")
+        sub_parser.add_argument("--process", dest="process_name", help="executable name filter")
+        sub_parser.add_argument("--pid", type=int, help="owning process id")
+        sub_parser.add_argument(
+            "--title-mode", default="auto", choices=["auto", "exact", "substring", "regex"]
+        )
+        sub_parser.add_argument("--monitor", default=None, help="auto | virtual | primary | DISPLAY2 | 1")
+        sub_parser.add_argument(
+            "--hide-mode",
+            default=None,
+            choices=["virtual_screen", "offscreen", "auto"],
+            help="virtual_screen = move onto the virtual display (default), "
+            "offscreen = park outside every monitor, auto = try the first then fall back",
+        )
+        sub_parser.add_argument(
+            "--virtual-size",
+            default=None,
+            help="resize the virtual desktop before mounting, e.g. 1920x1080 or 'main' (default: main)",
+        )
+        sub_parser.add_argument(
+            "--virtual-dpi",
+            default=None,
+            help="virtual desktop DPI, e.g. 120, '125%' or 'main' (default: main)",
+        )
+        sub_parser.add_argument(
+            "--keep-window-size",
+            action="store_true",
+            help="move the window without resizing it (safer for custom-rendered apps)",
+        )
+        sub_parser.add_argument("--timeout", type=float, default=10.0, help="window wait timeout")
+        sub_parser.add_argument("--padding", type=int, default=0)
+        sub_parser.add_argument("--keep-visible", action="store_true", help="show the window after mounting")
+        sub_parser.add_argument(
+            "--no-driver-install", action="store_true", help="never install a driver; fail instead"
+        )
+        sub_parser.add_argument("--out", help="write the captured PNG here")
+        sub_parser.add_argument("--client-only", action="store_true", default=None)
+        sub_parser.add_argument(
+            "--methods", help="comma-separated capture methods (default: all, in order)"
+        )
+        sub_parser.add_argument("--unmount", action="store_true", help="restore the window when done")
+        sub_parser.add_argument(
+            "--ui-tree", metavar="DIR", help="also export the window's UI tree into DIR"
+        )
+        sub_parser.add_argument(
+            "--desktop-shot", metavar="PNG", help="also save a shot of the whole virtual desktop"
+        )
+        if name == "capture":
+            sub_parser.add_argument(
+                "--no-mount", action="store_true", help="capture in place, without moving the window"
+            )
+
+    # -- internal (elevated child) --------------------------------------------------
+    internal = sub.add_parser(_INTERNAL, help=argparse.SUPPRESS)
+    internal.add_argument("--response-pipe", required=True)
+    internal.add_argument("--cache-dir")
+    internal.add_argument("--driver")
+    internal.add_argument("--strategy", default="auto")
+    internal.add_argument("--signature-policy", default="warn")
+    internal.add_argument("--install-timeout", type=float, default=600.0)
+    internal.add_argument("--log-dir")
+    internal.add_argument(
+        "--uninstall", action="store_true", help="privileged child: remove the device instead of adding it"
+    )
+    internal.add_argument("--purge-files", action="store_true")
+    internal.add_argument("--purge-driver-store", action="store_true")
+    internal.add_argument(
+        "--no-elevate",
+        action="store_true",
+        help="privileged child: already elevated, never request elevation again",
+    )
+    return parser
+
+
+def _driver_config_from(args: argparse.Namespace) -> DriverConfig:
+    config = DriverConfig()
+    updates: Dict[str, Any] = {}
+    for attribute, arg in (
+        ("driver", "driver"),
+        ("strategy", "strategy"),
+        ("signature_policy", "signature_policy"),
+        ("cache_dir", "cache_dir"),
+    ):
+        value = getattr(args, arg, None)
+        if value:
+            updates[attribute] = value
+    if getattr(args, "timeout", None):
+        updates["install_timeout"] = args.timeout
+    return type(config)(**{**config.__dict__, **updates}) if updates else config
+
+
+def _session_from(args: argparse.Namespace) -> OffscreenSession:
+    session_config = SessionConfig()
+    updates: Dict[str, Any] = {}
+    if getattr(args, "monitor", None):
+        updates["monitor"] = args.monitor
+    if getattr(args, "hide_mode", None):
+        updates["hide_mode"] = args.hide_mode
+    if getattr(args, "keep_window_size", False):
+        updates["keep_window_size"] = True
+    if getattr(args, "timeout", None):
+        updates["window_timeout"] = args.timeout
+    if getattr(args, "title_mode", None):
+        updates["title_mode"] = args.title_mode
+    if getattr(args, "padding", None) is not None:
+        updates["padding"] = args.padding
+    if getattr(args, "client_only", None) is not None:
+        updates["capture_client_only"] = bool(args.client_only)
+    if getattr(args, "methods", None):
+        updates["capture_methods"] = tuple(m.strip() for m in args.methods.split(",") if m.strip())
+    if updates:
+        session_config = type(session_config)(**{**session_config.__dict__, **updates})
+    return OffscreenSession(
+        target_window_title=getattr(args, "title", None),
+        window_class=getattr(args, "window_class", None),
+        process_name=getattr(args, "process_name", None),
+        window_pid=getattr(args, "pid", None),
+        driver=_driver_config_from(args),
+        config=session_config,
+    )
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    report = probe_environment(
+        driver_config=_driver_config_from(args),
+        window=getattr(args, "window", None),
+        capture_probe=getattr(args, "capture_probe", False),
+    )
+    if args.json:
+        _print(report, as_json=True)
+        return EXIT_CODES["ok"]
+    print(f"platform      : {'windows' if report['platform']['windows'] else 'NOT windows'}")
+    compat = report.get("compatibility") or {}
+    iddcx = report.get("iddcx") or {}
+    if compat:
+        print(f"windows       : {compat.get('described')} (dpi awareness: {compat.get('dpi_awareness')})")
+        if iddcx:
+            print(
+                f"iddcx         : {'supported' if iddcx.get('supported') else 'UNSUPPORTED'}"
+                f" (min build {iddcx.get('min_build')}, dll {iddcx.get('dll_version') or 'absent'})"
+            )
+    print(f"session type  : {report['platform']['session']}")
+    print(f"elevated      : {report['elevated']}")
+    print(f"desktop       : {report['desktop'] or '<unknown>'}")
+    print(f"monitors      : {len(report['monitors'])}")
+    for monitor in report["monitors"]:
+        marker = " <- primary" if monitor["primary"] else ""
+        print(
+            f"  {monitor['device']:<18} {monitor['width']}x{monitor['height']}"
+            f"+{monitor['monitor'][0]}+{monitor['monitor'][1]} {monitor['device_string']}{marker}"
+        )
+    driver = report.get("driver") or {}
+    print(f"driver device : {'present' if driver.get('device_present') else 'MISSING'} ({driver.get('driver')})")
+    if driver.get("error"):
+        print(f"driver error  : {driver['error']}")
+    if driver.get("cache"):
+        cache = driver["cache"]
+        print(f"cache dir     : {cache.get('cache_dir')}")
+        print(
+            f"artifact      : {cache.get('artifact')} "
+            f"({'cached' if cache.get('artifact_cached') else cache.get('artifact_reason')})"
+        )
+    if report.get("window"):
+        print(f"window        : {report['window']}")
+    if report.get("capture"):
+        for entry in report["capture"].get("methods", []):
+            print(f"capture {entry['method']:<18}: {'ok' if entry.get('ok') else entry.get('error')}")
+    print(f"verdict       : {report['verdict']}")
+    return EXIT_CODES["ok"]
+
+
+def _cmd_fetch_driver(args: argparse.Namespace) -> int:
+    config = _driver_config_from(args)
+    installer = config.installer()
+    bundle = installer.bundles.prepare_driver(
+        installer.spec, settings_file=config.settings_file or None
+    )
+    tool = installer.bundles.tool(installer.manifest, "nefcon")
+    payload = {
+        "driver": installer.spec.name,
+        "version": installer.spec.version,
+        "inf": str(bundle.inf_path),
+        "nefcon": str(tool),
+        "cache_dir": str(installer.cache_dir),
+        "verified": True,
+    }
+    if args.json:
+        _print(payload, as_json=True)
+    else:
+        for key, value in payload.items():
+            print(f"{key:<10}: {value}")
+    return EXIT_CODES["ok"]
+
+
+def _cmd_install_driver(args: argparse.Namespace) -> int:
+    config = _driver_config_from(args)
+    installer = config.installer()
+    if getattr(args, "dry_run", False):
+        bundle = installer.bundles.prepare_driver(
+            installer.spec, settings_file=config.settings_file or None
+        )
+        nefcon = installer.bundles.tool(installer.manifest, "nefcon")
+        commands = [
+            [str(nefcon), "install", str(bundle.inf_path), hw, "--no-duplicates"]
+            for hw in installer.spec.all_hardware_ids
+        ]
+        payload = {
+            "dry_run": True,
+            "device_present": installer.is_present(),
+            "elevated": is_admin(),
+            "inf": str(bundle.inf_path),
+            "commands": commands,
+            "helper": helper_command(
+                "--cache-dir",
+                str(installer.cache_dir),
+                "--strategy",
+                config.strategy,
+                "--signature-policy",
+                config.signature_policy,
+            ),
+            "signature_policy": config.signature_policy,
+        }
+        if args.json:
+            _print(payload, as_json=True)
+        else:
+            print("dry run: nothing was installed")
+            print(f"  device present : {payload['device_present']}")
+            print(f"  process elevated: {payload['elevated']}")
+            for command in commands:
+                print("  would run      : " + " ".join(f'"{c}"' if " " in c else c for c in command))
+            print("  helper (if UAC needed):")
+            print("    " + " ".join(f'"{c}"' if " " in c else c for c in payload["helper"]))
+        return EXIT_CODES["ok"]
+
+    policy = config.policy
+    try:
+        if policy == "always" or not installer.is_present():
+            report = installer.ensure(allow_install=True)
+        else:
+            report = installer.detect()
+            report.skipped_reason = "already-installed"
+    except OffscreenMountError as exc:
+        payload = {"ok": False, "error": exc.to_dict()}
+        _print(payload, as_json=args.json)
+        if not args.json:
+            print(f"error: {exc}", file=sys.stderr)
+        return _exit_code_for(exc)
+    _print({"ok": True, **report.to_dict()}, as_json=args.json)
+    if not args.json:
+        print(
+            f"driver {report.driver} {report.version}: "
+            f"{'present' if report.device_present else 'installed, monitor pending'}"
+            f"{' (reboot required)' if report.requires_reboot else ''}"
+        )
+    return EXIT_CODES["ok"]
+
+
+def _cmd_uninstall_driver(args: argparse.Namespace) -> int:
+    config = _driver_config_from(args)
+    installer = config.installer()
+    report = installer.uninstall(
+        purge_files=getattr(args, "purge_files", False),
+        purge_driver_store=getattr(args, "purge_driver_store", False),
+    )
+    _print({"ok": report.ok, **report.to_dict()}, as_json=args.json)
+    return EXIT_CODES["ok"]
+
+
+def _cmd_list_windows(args: argparse.Namespace) -> int:
+    records = list_windows()
+    needle = (args.filter or "").lower()
+    rows: List[dict] = []
+    for record in records:
+        if not args.all and (not record.visible or not record.title or record.tool_window):
+            continue
+        if needle and needle not in record.title.lower():
+            continue
+        rows.append(
+            {
+                "hwnd": hex(record.hwnd),
+                "title": record.title,
+                "class": record.class_name,
+                "process": record.process_name,
+                "pid": record.pid,
+                "rect": list(record.rect),
+            }
+        )
+    if args.json:
+        _print(rows, as_json=True)
+        return EXIT_CODES["ok"]
+    if not rows:
+        print("no matching windows")
+        return EXIT_CODES["ok"]
+    print(f"{'hwnd':<12} {'pid':<7} {'process':<24} title")
+    for row in rows:
+        print(f"{row['hwnd']:<12} {row['pid']:<7} {row['process'][:23]:<24} {row['title'][:70]}")
+    return EXIT_CODES["ok"]
+
+
+def _export_ui_tree(hwnd: int, out_dir: str) -> Dict[str, Any]:
+    """Export a window's UI tree (UI Automation + native children) into ``out_dir``.
+
+    The exporter ships in ``tools/ui_tree_export.py`` because it needs the PowerShell UIA helper
+    (``tools/uia_dump.ps1``); when that helper is not present the call degrades to a clear error
+    instead of failing the capture that already succeeded.
+    """
+    if not hwnd:
+        return {"error": "no window handle available"}
+    import importlib.util
+
+    candidates = [
+        Path(__file__).resolve().parent.parent / "tools" / "ui_tree_export.py",
+        Path.cwd() / "tools" / "ui_tree_export.py",
+    ]
+    for candidate in candidates:
+        if not candidate.is_file():
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location("_offscreen_ui_tree_export", candidate)
+            if spec is None or spec.loader is None:
+                continue
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[spec.name] = module
+            spec.loader.exec_module(module)
+            tools_dir = str(candidate.parent)
+            if tools_dir not in sys.path:
+                sys.path.insert(0, tools_dir)
+            return module.export_hwnd(hwnd, out_dir, label="window")
+        except Exception as exc:  # noqa: BLE001 - reported, never fatal
+            return {"error": f"{type(exc).__name__}: {exc}"[:300]}
+    return {
+        "error": "ui_tree_export.py was not found next to the library or in ./tools; "
+        "run `python tools/ui_tree_export.py --hwnd 0x… --out-dir DIR` instead"
+    }
+
+
+def _cmd_mount_or_capture(args: argparse.Namespace, *, capture: bool) -> int:
+    session = _session_from(args)
+    install_driver = not getattr(args, "no_driver_install", False)
+    do_mount = True
+    if capture and getattr(args, "no_mount", False):
+        do_mount = False
+
+    # Optional virtual-desktop preparation (size / DPI), done before the window is mounted so the
+    # target monitor already has its final geometry.
+    display_setup = None
+    if getattr(args, "virtual_size", None) or getattr(args, "virtual_dpi", None):
+        from .display_setup import configure_virtual_display, parse_dpi, parse_size
+
+        # "main"/None must be passed through as None so the helper applies the documented default
+        # (follow the primary monitor) instead of being misread as "no change requested".
+        display_setup = configure_virtual_display(
+            size=parse_size(args.virtual_size) if args.virtual_size not in (None, "main") else "main",
+            dpi=parse_dpi(args.virtual_dpi) if args.virtual_dpi not in (None, "main") else "main",
+        )
+        log = __import__("VirtualDesktop._log", fromlist=["get_logger"]).get_logger("cli")
+        log.info("virtual display setup: %s", display_setup.to_dict())
+        if not args.json:
+            print(
+                f"virtual display: {display_setup.effective_size} @ {display_setup.effective_dpi} dpi "
+                f"(size_applied={display_setup.size_applied}, dpi_applied={display_setup.dpi_applied}"
+                + (f", skipped={display_setup.skipped}" if display_setup.skipped else "")
+                + ")"
+            )
+
+    try:
+        if do_mount:
+            session.mount(
+                install_driver=install_driver,
+                visible=True if getattr(args, "keep_visible", False) else None,
+            )
+        if capture:
+            if not do_mount:
+                # Capture in place: resolve the window without moving it.
+                record = find_window(
+                    title=session.config.target_window_title,
+                    class_name=session.config.window_class,
+                    process_name=session.config.process_name,
+                    pid=session.config.window_pid,
+                    timeout=session.config.window_timeout,
+                )
+                from .capture import DEFAULT_METHODS, CaptureEngine
+
+                engine = CaptureEngine(
+                    client_only=session.config.capture_client_only,
+                    validate=session.config.capture_validate,
+                    methods=session.config.capture_methods or DEFAULT_METHODS,
+                )
+                frame = engine.capture(record.hwnd, save_to=args.out)
+            else:
+                frame = session.capture(save_to=args.out)
+            payload = {
+                "ok": True,
+                "saved": args.out,
+                "method": frame.method,
+                "size": list(frame.size),
+                "analysis": frame.analysis.to_dict() if frame.analysis else None,
+                "window": session.report().get("window"),
+                "monitor": session.report().get("monitor"),
+                "hide_mode_used": session.hide_mode_used,
+                "display_setup": display_setup.to_dict() if display_setup else None,
+            }
+            # Optional artifacts: a whole-desktop shot and the window's UI tree.
+            if getattr(args, "desktop_shot", None):
+                from .desktop_capture import capture_all_screens, capture_monitor
+
+                try:
+                    shot = capture_monitor() if session.monitor else capture_all_screens()
+                    shot.save(args.desktop_shot)
+                    payload["desktop_shot"] = shot.to_dict() | {"file": args.desktop_shot}
+                except Exception as exc:  # noqa: BLE001 - the capture itself already succeeded
+                    payload["desktop_shot"] = {"error": str(exc)[:300]}
+            if getattr(args, "ui_tree", None):
+                payload["ui_tree"] = _export_ui_tree(
+                    (session.hwnd or 0) if do_mount else record.hwnd, args.ui_tree
+                )
+            _print(payload, as_json=args.json)
+            if not args.json:
+                print(
+                    f"captured {frame.size[0]}x{frame.size[1]} via {frame.method}"
+                    + (f" -> {args.out}" if args.out else "")
+                )
+                if payload.get("desktop_shot", {}).get("file"):
+                    print(f"desktop shot -> {payload['desktop_shot']['file']}")
+                if payload.get("ui_tree"):
+                    tree = payload["ui_tree"]
+                    print(
+                        f"ui tree -> {tree.get('uia_count')} UIA element(s), "
+                        f"{tree.get('native_children')} native child window(s) in {args.ui_tree}"
+                    )
+        else:
+            _print({"ok": True, **session.report()}, as_json=args.json)
+    except OffscreenMountError as exc:
+        _print({"ok": False, "error": exc.to_dict()}, as_json=args.json)
+        if not args.json:
+            print(f"error: {exc}", file=sys.stderr)
+        return _exit_code_for(exc)
+    finally:
+        if getattr(args, "unmount", False) or (capture and do_mount and not args.json):
+            session.unmount()
+    return EXIT_CODES["ok"]
+
+
+def _write_helper_trace(payload: Dict[str, Any]) -> None:
+    """Best-effort breadcrumb from the elevated child.
+
+    Set ``VIRTUALDESKTOP_HELPER_TRACE`` to a file path to have the child record that it started
+    and what it reported, *independently of the response pipe*.  Debugging an elevated helper
+    is otherwise blind: its stdout goes nowhere and the parent may never see a pipe message.
+    """
+    path = os.environ.get("VIRTUALDESKTOP_HELPER_TRACE")
+    if not path:
+        return
+    try:
+        import time as _time
+
+        line = json.dumps(
+            {
+                "ts": _time.time(),
+                "pid": os.getpid(),
+                "elevated": is_admin(),
+                "argv": sys.argv,
+                **payload,
+            },
+            default=str,
+        )
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(line + "\n")
+    except OSError:  # pragma: no cover - tracing must never break the install
+        pass
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    _configure_console()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.debug or os.environ.get("VIRTUALDESKTOP_DEBUG"):
+        enable_debug_logging(log_file=args.log_file)
+    elif args.log_file:
+        enable_debug_logging(level=20, stream=None, log_file=args.log_file)
+
+    if not IS_WINDOWS and args.command != "check":
+        print("VirtualDesktop only runs on Windows.", file=sys.stderr)
+        return EXIT_CODES["unsupported-platform"]
+
+    try:
+        if args.command == _INTERNAL:
+            _write_helper_trace({"event": "helper-start", "cache_dir": args.cache_dir})
+            return install_from_helper(
+                cache_dir=args.cache_dir,
+                strategy=args.strategy,
+                signature_policy=args.signature_policy,
+                driver=args.driver,
+                install_timeout=args.install_timeout,
+                log_dir=args.log_dir,
+                response_pipe=args.response_pipe,
+                uninstall=getattr(args, "uninstall", False),
+                purge_files=getattr(args, "purge_files", False),
+                purge_driver_store=getattr(args, "purge_driver_store", False),
+                elevate=not getattr(args, "no_elevate", False),
+            )
+        if args.command == "check":
+            return _cmd_check(args)
+        if args.command == "fetch-driver":
+            return _cmd_fetch_driver(args)
+        if args.command == "install-driver":
+            return _cmd_install_driver(args)
+        if args.command == "uninstall-driver":
+            return _cmd_uninstall_driver(args)
+        if args.command == "list-windows":
+            return _cmd_list_windows(args)
+        if args.command == "mount":
+            return _cmd_mount_or_capture(args, capture=False)
+        if args.command == "capture":
+            return _cmd_mount_or_capture(args, capture=True)
+        parser.error(f"unknown command {args.command!r}")
+        return EXIT_CODES["usage"]
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        print("interrupted", file=sys.stderr)
+        return 130
+    except OffscreenMountError as exc:
+        _print({"ok": False, "error": exc.to_dict()}, as_json=getattr(args, "json", False))
+        if not getattr(args, "json", False):
+            print(f"error: {exc}", file=sys.stderr)
+        return _exit_code_for(exc)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())