isHeadlessOrRemoteSession function

bool isHeadlessOrRemoteSession({
  1. Map<String, String>? environment,
  2. bool? stdoutHasTerminal,
  3. bool? isLinux,
})

Whether the current session looks headless or remote (gh-1450): no graphical display on Linux, an SSH session marker, or a non-interactive stdout. Such sessions cannot show a browser window the user controls — exactly the incident's setting (the launch "succeeds" into a browser the user never sees) — so flows skip the automatic launch and print the authorization URL prominently instead.

environment/stdoutHasTerminal/isLinux are injectable seams for tests; production resolves them from Platform.environment, stdout.hasTerminal, and Platform.isLinux.

Implementation

bool isHeadlessOrRemoteSession({
  Map<String, String>? environment,
  bool? stdoutHasTerminal,
  bool? isLinux,
}) {
  String? value(String name) {
    final v = (environment ?? Platform.environment)[name]?.trim();
    return v == null || v.isEmpty ? null : v;
  }

  if (isLinux ?? Platform.isLinux) {
    // Linux: a graphical display is mandatory for a visible browser.
    if (value('DISPLAY') == null && value('WAYLAND_DISPLAY') == null) {
      return true;
    }
  }
  if (value('SSH_TTY') != null || value('SSH_CONNECTION') != null) {
    return true;
  }
  return !(stdoutHasTerminal ?? stdout.hasTerminal);
}