feat(core): implement automatic terminal detection and capability warnings (#14426)

packages/core/src/utils/compatibility.ts

@@ -8,7 +8,6 @@ import os from 'node:os';
 
 /**
  * Detects if the current OS is Windows 10.
- * Windows 11 also reports as version 10.0, but with build numbers >= 22000.
  */
 export function isWindows10(): boolean {
   if (os.platform() !== 'win32') {
@@ -27,7 +26,12 @@ export function isWindows10(): boolean {
  * Detects if the current terminal is a JetBrains-based IDE terminal.
  */
 export function isJetBrainsTerminal(): boolean {
-  return process.env['TERMINAL_EMULATOR'] === 'JetBrains-JediTerm';
+  return (
+    process.env['TERMINAL_EMULATOR'] === 'JetBrains-JediTerm' ||
+    process.env['TERM_PROGRAM'] === 'JetBrains-JediTerm' ||
+    !!process.env['IDEA_INITIAL_DIRECTORY'] ||
+    !!process.env['JETBRAINS_IDE']
+  );
 }
 
 /**
@@ -37,6 +41,44 @@ export function isAppleTerminal(): boolean {
   return process.env['TERM_PROGRAM'] === 'Apple_Terminal';
 }
 
+/**
+ * Detects if the current terminal is VS Code.
+ */
+export function isVSCode(): boolean {
+  return process.env['TERM_PROGRAM'] === 'vscode';
+}
+
+/**
+ * Detects if the current terminal is iTerm2.
+ */
+export function isITerm2(): boolean {
+  return process.env['TERM_PROGRAM'] === 'iTerm.app';
+}
+
+/**
+ * Detects if the current terminal is Ghostty.
+ */
+export function isGhostty(): boolean {
+  return (
+    process.env['TERM_PROGRAM'] === 'ghostty' ||
+    !!process.env['GHOSTTY_BIN_DIR']
+  );
+}
+
+/**
+ * Detects if running inside tmux.
+ */
+export function isTmux(): boolean {
+  return !!process.env['TMUX'] || (process.env['TERM'] || '').includes('tmux');
+}
+
+/**
+ * Detects if the current terminal is Windows Terminal.
+ */
+export function isWindowsTerminal(): boolean {
+  return !!process.env['WT_SESSION'];
+}
+
 /**
  * Detects if the current terminal supports 256 colors (8-bit).
  */
@@ -75,6 +117,13 @@ export function supportsTrueColor(): boolean {
   return false;
 }
 
+/**
+ * Heuristic for keyboard protocol support based on terminal identity.
+ */
+export function supportsKeyboardProtocolHeuristic(): boolean {
+  return isGhostty() || isITerm2() || isVSCode() || isWindowsTerminal();
+}
+
 export enum WarningPriority {
   Low = 'low',
   High = 'high',
@@ -91,6 +140,7 @@ export interface StartupWarning {
  */
 export function getCompatibilityWarnings(options?: {
   isAlternateBuffer?: boolean;
+  supportsKeyboardProtocol?: boolean;
 }): StartupWarning[] {
   const warnings: StartupWarning[] = [];
 
@@ -114,11 +164,20 @@ export function getCompatibilityWarnings(options?: {
 
     warnings.push({
       id: 'jetbrains-terminal',
-      message: `Warning: JetBrains mouse scrolling is unreliable. Disabling alternate buffer mode in settings or using an external terminal${suggestedTerminals} is recommended.`,
+      message: `Warning: JetBrains mouse scrolling is unreliable with alternate buffer enabled. Using an external terminal${suggestedTerminals} or disabling alternate buffer in settings is recommended.`,
       priority: WarningPriority.High,
     });
   }
 
+  if (isTmux()) {
+    warnings.push({
+      id: 'tmux-mouse-support',
+      message:
+        'Warning: Running inside tmux. For the best experience (including mouse scrolling), ensure "set -g mouse on" is enabled in your tmux configuration.',
+      priority: WarningPriority.Low,
+    });
+  }
+
   if (!supports256Colors()) {
     warnings.push({
       id: '256-color',
@@ -126,7 +185,13 @@ export function getCompatibilityWarnings(options?: {
         'Warning: 256-color support not detected. Using a terminal with at least 256-color support is recommended for a better visual experience.',
       priority: WarningPriority.High,
     });
-  } else if (!supportsTrueColor() && !isAppleTerminal()) {
+  } else if (
+    !supportsTrueColor() &&
+    !isITerm2() &&
+    !isVSCode() &&
+    !isGhostty() &&
+    !isAppleTerminal()
+  ) {
     warnings.push({
       id: 'true-color',
       message:
@@ -135,5 +200,23 @@ export function getCompatibilityWarnings(options?: {
     });
   }
 
+  const hasKeyboardProtocol =
+    options?.supportsKeyboardProtocol ?? supportsKeyboardProtocolHeuristic();
+
+  if (!hasKeyboardProtocol) {
+    const suggestion =
+      os.platform() === 'darwin'
+        ? 'iTerm2 or Ghostty'
+        : os.platform() === 'win32'
+          ? 'Windows Terminal'
+          : 'Ghostty';
+
+    warnings.push({
+      id: 'keyboard-protocol',
+      message: `Warning: Advanced keyboard features (like Shift+Enter for newlines) are not supported in this terminal. Consider using ${suggestion} for a better experience.`,
+      priority: WarningPriority.Low,
+    });
+  }
+
   return warnings;
 }