Fix iterm alternate buffer mode issue rendering backgrounds (#17634)

packages/cli/src/ui/utils/terminalUtils.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { isITerm2, resetITerm2Cache } from './terminalUtils.js';
+
+describe('terminalUtils', () => {
+  beforeEach(() => {
+    vi.stubEnv('TERM_PROGRAM', '');
+    vi.stubEnv('ITERM_SESSION_ID', '');
+    resetITerm2Cache();
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  it('should detect iTerm2 via TERM_PROGRAM', () => {
+    vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
+    expect(isITerm2()).toBe(true);
+  });
+
+  it('should detect iTerm2 via ITERM_SESSION_ID', () => {
+    vi.stubEnv('ITERM_SESSION_ID', 'w0t0p0:6789...');
+    expect(isITerm2()).toBe(true);
+  });
+
+  it('should return false if not iTerm2', () => {
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    expect(isITerm2()).toBe(false);
+  });
+
+  it('should cache the result', () => {
+    vi.stubEnv('TERM_PROGRAM', 'iTerm.app');
+    expect(isITerm2()).toBe(true);
+
+    // Change env but should still be true due to cache
+    vi.stubEnv('TERM_PROGRAM', 'vscode');
+    expect(isITerm2()).toBe(true);
+
+    resetITerm2Cache();
+    expect(isITerm2()).toBe(false);
+  });
+});

packages/cli/src/ui/utils/terminalUtils.ts

@@ -20,3 +20,28 @@ export function getColorDepth(): number {
 export function isLowColorDepth(): boolean {
   return getColorDepth() < 24;
 }
+
+let cachedIsITerm2: boolean | undefined;
+
+/**
+ * Returns true if the current terminal is iTerm2.
+ */
+export function isITerm2(): boolean {
+  if (cachedIsITerm2 !== undefined) {
+    return cachedIsITerm2;
+  }
+
+  cachedIsITerm2 =
+    process.env['TERM_PROGRAM'] === 'iTerm.app' ||
+    !!process.env['ITERM_SESSION_ID'];
+
+  return cachedIsITerm2;
+}
+
+/**
+ * Resets the cached iTerm2 detection value.
+ * Primarily used for testing.
+ */
+export function resetITerm2Cache(): void {
+  cachedIsITerm2 = undefined;
+}