detect.py

Go to the documentation of this file.

# Copyright (c) 2025-present Aquin Labs Private Limited. All Rights Reserved.
"""Detect whether the current environment can run the Aquin Textual TUI."""
 
from __future__ import annotations
 
import importlib.util
import os
import sys
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass
from typing import Literal
 
Platform = Literal["linux", "darwin", "windows", "unknown"]
 
_DUMB_TERMS = frozenset({"", "dumb", "unknown"})
_CI_TRUTHY = frozenset({"1", "true", "yes", "on"})
 
 
@dataclass(frozen=True)
class TuiCapability:
    platform: Platform
    tty_ok: bool
    term_ok: bool
    textual_ok: bool
    tui_ok: bool
    reason: str
 
 
def detect_platform(*, sys_platform: str | None = None) -> Platform:
    """Map ``sys.platform`` to a coarse OS bucket used for TUI routing."""
    raw = (sys_platform if sys_platform is not None else sys.platform).lower()
    if raw.startswith("linux"):
        return "linux"
    if raw == "darwin":
        return "darwin"
    if raw == "win32":
        return "windows"
    return "unknown"
 
 
def _truthy_env(value: str | None) -> bool:
    return (value or "").strip().lower() in _CI_TRUTHY
 
 
def _opt_out_reason(argv: Sequence[str], environ: Mapping[str, str]) -> str | None:
    if "--plain" in argv:
        return "opt_out: --plain"
    if _truthy_env(environ.get("NO_TUI")):
        return "opt_out: NO_TUI"
    if _truthy_env(environ.get("CI")):
        return "opt_out: CI"
    return None
 
 
def _tty_ok(
    *,
    stdin_isatty: Callable[[], bool],
    stdout_isatty: Callable[[], bool],
) -> tuple[bool, str]:
    if not stdin_isatty():
        return False, "not_tty: stdin"
    if not stdout_isatty():
        return False, "not_tty: stdout"
    return True, "ok"
 
 
def _posix_term_ok(environ: Mapping[str, str]) -> tuple[bool, str]:
    term = (environ.get("TERM") or "").strip().lower()
    if term in _DUMB_TERMS:
        if not term:
            return False, "term_dumb: TERM unset"
        return False, f"term_dumb: TERM={term}"
    return True, "ok"
 
 
def _windows_vt_from_environ(environ: Mapping[str, str]) -> bool:
    if environ.get("WT_SESSION"):
        return True
    if environ.get("TERM_PROGRAM") in {"vscode", "Cursor", "iTerm.app"}:
        return True
    # Cursor / VS Code integrated terminals often expose these.
    if environ.get("VSCODE_INJECTION") or environ.get("CURSOR_TRACE_ID"):
        return True
    term = (environ.get("TERM") or "").strip().lower()
    if term.startswith("xterm") or term.startswith("tmux") or term == "ansi":
        return True
    return False
 
 
def _windows_vt_capable_default() -> bool:
    """Return whether stdout is a VT-capable Windows console."""
    if _windows_vt_from_environ(os.environ):
        return True
 
    try:
        import ctypes
        from ctypes import wintypes
    except Exception:
        return False
 
    kernel32 = ctypes.windll.kernel32
    std_output_handle = -11
    enable_virtual_terminal_processing = 0x0004
 
    handle = kernel32.GetStdHandle(std_output_handle)
    if handle == wintypes.HANDLE(-1).value:
        return False
 
    mode = ctypes.c_uint()
    if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
        return False
 
    if mode.value & enable_virtual_terminal_processing:
        return True
 
    new_mode = mode.value | enable_virtual_terminal_processing
    if kernel32.SetConsoleMode(handle, new_mode):
        kernel32.SetConsoleMode(handle, mode.value)
        return True
    return False
 
 
def _term_ok(
    platform: Platform,
    environ: Mapping[str, str],
    *,
    windows_vt_capable: Callable[[], bool],
) -> tuple[bool, str]:
    if platform == "windows":
        if _windows_vt_from_environ(environ) or windows_vt_capable():
            return True, "ok"
        return False, "term_not_vt_capable"
 
    # Linux, Darwin, and unknown POSIX-like hosts use TERM.
    return _posix_term_ok(environ)
 
 
def _textual_importable_default() -> bool:
    return importlib.util.find_spec("textual") is not None
 
 
def detect_tui_capability(
    *,
    argv: Sequence[str] | None = None,
    environ: Mapping[str, str] | None = None,
    stdin_isatty: Callable[[], bool] | None = None,
    stdout_isatty: Callable[[], bool] | None = None,
    sys_platform: str | None = None,
    textual_importable: Callable[[], bool] | None = None,
    windows_vt_capable: Callable[[], bool] | None = None,
) -> TuiCapability:
    """Return whether the Aquin Textual TUI should launch for this process."""
    argv = list(argv if argv is not None else sys.argv)
    environ = dict(environ if environ is not None else os.environ)
    stdin_isatty = stdin_isatty or sys.stdin.isatty
    stdout_isatty = stdout_isatty or sys.stdout.isatty
    textual_importable = textual_importable or _textual_importable_default
    windows_vt_capable = windows_vt_capable or _windows_vt_capable_default
 
    platform = detect_platform(sys_platform=sys_platform)
 
    opt_out = _opt_out_reason(argv, environ)
    if opt_out:
        return TuiCapability(
            platform=platform,
            tty_ok=False,
            term_ok=False,
            textual_ok=False,
            tui_ok=False,
            reason=opt_out,
        )
 
    tty_ok, tty_reason = _tty_ok(
        stdin_isatty=stdin_isatty,
        stdout_isatty=stdout_isatty,
    )
    if not tty_ok:
        return TuiCapability(
            platform=platform,
            tty_ok=False,
            term_ok=False,
            textual_ok=False,
            tui_ok=False,
            reason=tty_reason,
        )
 
    term_ok, term_reason = _term_ok(
        platform,
        environ,
        windows_vt_capable=windows_vt_capable,
    )
    if not term_ok:
        return TuiCapability(
            platform=platform,
            tty_ok=True,
            term_ok=False,
            textual_ok=False,
            tui_ok=False,
            reason=term_reason,
        )
 
    textual_ok = textual_importable()
    if not textual_ok:
        return TuiCapability(
            platform=platform,
            tty_ok=True,
            term_ok=True,
            textual_ok=False,
            tui_ok=False,
            reason="textual_not_installed",
        )
 
    return TuiCapability(
        platform=platform,
        tty_ok=True,
        term_ok=True,
        textual_ok=True,
        tui_ok=True,
        reason="ok",
    )