gemini-cli/packages/cli/src/ui/utils/terminalCapabilityManager.test.ts

/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { TerminalCapabilityManager } from './terminalCapabilityManager.js';
import { EventEmitter } from 'node:events';
import {
  enableKittyKeyboardProtocol,
  enableModifyOtherKeys,
} from '@google/gemini-cli-core';
import * as fs from 'node:fs';

// Mock fs
vi.mock('node:fs', () => ({
  writeSync: vi.fn(),
}));

// Mock core
vi.mock('@google/gemini-cli-core', () => ({
  debugLogger: {
    log: vi.fn(),
    warn: vi.fn(),
  },
  enableKittyKeyboardProtocol: vi.fn(),
  disableKittyKeyboardProtocol: vi.fn(),
  enableModifyOtherKeys: vi.fn(),
  disableModifyOtherKeys: vi.fn(),
  enableBracketedPasteMode: vi.fn(),
  disableBracketedPasteMode: vi.fn(),
}));

describe('TerminalCapabilityManager', () => {
  let stdin: EventEmitter & {
    isTTY?: boolean;
    isRaw?: boolean;
    setRawMode?: (mode: boolean) => void;
    removeListener?: (
      event: string,
      listener: (...args: unknown[]) => void,
    ) => void;
  };
  let stdout: { isTTY?: boolean; fd?: number };
  // Save original process properties
  const originalStdin = process.stdin;
  const originalStdout = process.stdout;

  beforeEach(() => {
    vi.resetAllMocks();
    vi.useFakeTimers();

    // Reset singleton
    TerminalCapabilityManager.resetInstanceForTesting();

    // Setup process mocks
    stdin = new EventEmitter();
    stdin.isTTY = true;
    stdin.isRaw = false;
    stdin.setRawMode = vi.fn();
    stdout = { isTTY: true, fd: 1 };

    // Use defineProperty to mock process properties
    Object.defineProperty(process, 'stdin', {
      value: stdin,
      configurable: true,
    });
    Object.defineProperty(process, 'stdout', {
      value: stdout,
      configurable: true,
    });
  });

  afterEach(() => {
    vi.useRealTimers();
    // Restore original process properties
    Object.defineProperty(process, 'stdin', {
      value: originalStdin,
      configurable: true,
    });
    Object.defineProperty(process, 'stdout', {
      value: originalStdout,
      configurable: true,
    });
  });

  it('should detect Kitty support when u response is received', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Simulate kitty protocol response
    stdin.emit('data', Buffer.from('\x1b[?1u'));
    // Simulate sentinel response
    stdin.emit('data', Buffer.from('\x1b[?1c'));

    await promise;
    expect(manager.isKittyProtocolEnabled()).toBe(true);
    expect(enableKittyKeyboardProtocol).toHaveBeenCalled();
  });

  it('should detect Background Color', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Simulate background color response
    stdin.emit('data', Buffer.from('\x1b]11;rgb:0000/ffff/0000\x1b\\'));
    // Simulate sentinel response
    stdin.emit('data', Buffer.from('\x1b[?1c'));

    await promise;
    expect(manager.getTerminalBackgroundColor()).toBe('#00ff00');
  });

  it('should detect Terminal Name', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Simulate terminal name response
    stdin.emit('data', Buffer.from('\x1bP>|WezTerm 20240203\x1b\\'));
    // Simulate sentinel response
    stdin.emit('data', Buffer.from('\x1b[?1c'));

    await promise;
    expect(manager.getTerminalName()).toBe('WezTerm 20240203');
  });

  it('should complete early if sentinel (DA1) is found', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Send everything at once
    stdin.emit(
      'data',
      Buffer.from(
        '\x1b[?1u\x1b]11;rgb:0000/0000/0000\x1b\\\x1bP>|xterm\x1b\\\x1b[?1c',
      ),
    );

    await promise;
    expect(manager.isKittyProtocolEnabled()).toBe(true);
    expect(manager.getTerminalBackgroundColor()).toBe('#000000');
  });

  it('should timeout if no DA1 (c) is received', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Don't send any data, just trigger timeout
    vi.advanceTimersByTime(1000);

    await promise;
    expect(manager.getTerminalBackgroundColor()).toBeUndefined();
  });

  it('should not detect Kitty if only DA1 (c) is received', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Send only sentinel
    stdin.emit('data', Buffer.from('\x1b[?1c'));

    await promise;
    expect(manager.isKittyProtocolEnabled()).toBe(false);
  });

  it('should handle split chunks', async () => {
    const manager = TerminalCapabilityManager.getInstance();
    const promise = manager.detectCapabilities();

    // Split background color response
    stdin.emit('data', Buffer.from('\x1b]11;'));
    stdin.emit('data', Buffer.from('rgb:ffff/0000/0000\x1b\\'));
    stdin.emit('data', Buffer.from('\x1b[?1c'));

    await promise;
    expect(manager.getTerminalBackgroundColor()).toBe('#ff0000');
  });

  describe('modifyOtherKeys detection', () => {
    it('should detect modifyOtherKeys support (level 2)', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      // level 2
      stdin.emit('data', Buffer.from('\x1b[>4;2m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(enableModifyOtherKeys).toHaveBeenCalled();
    });

    it('should not enable modifyOtherKeys for level 0', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      // level 0 (disabled)
      stdin.emit('data', Buffer.from('\x1b[>4;0m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(enableModifyOtherKeys).not.toHaveBeenCalled();
    });

    it('should prefer Kitty over modifyOtherKeys', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      stdin.emit('data', Buffer.from('\x1b[?1u'));
      stdin.emit('data', Buffer.from('\x1b[>4;2m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(enableKittyKeyboardProtocol).toHaveBeenCalled();
      expect(enableModifyOtherKeys).not.toHaveBeenCalled();
    });

    it('should enable modifyOtherKeys when Kitty not supported', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      stdin.emit('data', Buffer.from('\x1b[>4;2m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(manager.isKittyProtocolEnabled()).toBe(false);
      expect(enableModifyOtherKeys).toHaveBeenCalled();
    });

    it('should handle split modifyOtherKeys response chunks', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      stdin.emit('data', Buffer.from('\x1b[>4;'));
      stdin.emit('data', Buffer.from('2m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(enableModifyOtherKeys).toHaveBeenCalled();
    });

    it('should detect modifyOtherKeys with other capabilities', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      stdin.emit('data', Buffer.from('\x1b]11;rgb:1a1a/1a1a/1a1a\x1b\\'));
      stdin.emit('data', Buffer.from('\x1bP>|tmux\x1b\\'));
      stdin.emit('data', Buffer.from('\x1b[>4;2m'));
      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(manager.getTerminalBackgroundColor()).toBe('#1a1a1a');
      expect(manager.getTerminalName()).toBe('tmux');
      expect(enableModifyOtherKeys).toHaveBeenCalled();
    });

    it('should not enable modifyOtherKeys without explicit response', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      const promise = manager.detectCapabilities();

      stdin.emit('data', Buffer.from('\x1b[?1c'));

      await promise;

      expect(manager.isKittyProtocolEnabled()).toBe(false);
      expect(enableModifyOtherKeys).not.toHaveBeenCalled();
    });

    it('should wrap queries in hidden/clear sequence', async () => {
      const manager = TerminalCapabilityManager.getInstance();
      void manager.detectCapabilities();

      expect(fs.writeSync).toHaveBeenCalledWith(
        expect.anything(),
        // eslint-disable-next-line no-control-regex
        expect.stringMatching(/^\x1b\[8m.*?\x1b\[2K\r\x1b\[0m$/),
      );
    });
  });

  describe('supportsOsc9Notifications', () => {
    const testCases = [
      {
        name: 'WezTerm (terminal name)',
        terminalName: 'WezTerm 20240203',
        env: {},
        expected: true,
      },
      {
        name: 'iTerm.app (terminal name)',
        terminalName: 'iTerm.app',
        env: {},
        expected: true,
      },
      {
        name: 'ghostty (terminal name)',
        terminalName: 'ghostty',
        env: {},
        expected: true,
      },
      {
        name: 'kitty (terminal name)',
        terminalName: 'xterm-kitty',
        env: {},
        expected: true,
      },
      {
        name: 'some-other-term (terminal name)',
        terminalName: 'some-other-term',
        env: {},
        expected: false,
      },
      {
        name: 'iTerm.app (TERM_PROGRAM)',
        terminalName: undefined,
        env: { TERM_PROGRAM: 'iTerm.app' },
        expected: true,
      },
      {
        name: 'vscode (TERM_PROGRAM)',
        terminalName: undefined,
        env: { TERM_PROGRAM: 'vscode' },
        expected: false,
      },
      {
        name: 'xterm-kitty (TERM)',
        terminalName: undefined,
        env: { TERM: 'xterm-kitty' },
        expected: true,
      },
      {
        name: 'xterm-256color (TERM)',
        terminalName: undefined,
        env: { TERM: 'xterm-256color' },
        expected: false,
      },
    ];

    testCases.forEach(({ name, terminalName, env, expected }) => {
      it(`should return ${expected} for '${name}'`, () => {
        const manager = TerminalCapabilityManager.getInstance();
        vi.spyOn(manager, 'getTerminalName').mockReturnValue(terminalName);
        expect(manager.supportsOsc9Notifications(env)).toBe(expected);
      });
    });
  });
});