MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

feat(core): centralize compatibility checks and add TrueColor detection (#19478)

Browse Source
This commit is contained in:
Spencer
2026-02-18 19:01:23 -05:00
committed by GitHub
parent ef65498031
commit c62340675a
10 changed files with 301 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/cli/settings.md
View File

@@ -50,6 +50,7 @@ they appear in the UI.
| Show Thoughts in Title | `ui.showStatusInTitle` | Show Gemini CLI model thoughts in the terminal window title during the working phase | `false` |
| Dynamic Window Title | `ui.dynamicWindowTitle` | Update the terminal window title with current status icons (Ready: ◇, Action Required: ✋, Working: ✦) | `true` |
| Show Home Directory Warning | `ui.showHomeDirectoryWarning` | Show a warning when running Gemini CLI in the home directory. | `true` |
| Show Compatibility Warnings | `ui.showCompatibilityWarnings` | Show warnings about terminal or OS compatibility issues. | `true` |
| Hide Tips | `ui.hideTips` | Hide helpful tips in the UI | `false` |
| Show Shortcuts Hint | `ui.showShortcutsHint` | Show the "? for shortcuts" hint above the input. | `true` |
| Hide Banner | `ui.hideBanner` | Hide the application banner | `false` |

5
docs/get-started/configuration.md
View File

@@ -233,6 +233,11 @@ their corresponding top-level category object in your `settings.json` file.
- **Default:** `true`
- **Requires restart:** Yes
- **`ui.showCompatibilityWarnings`** (boolean):
- **Description:** Show warnings about terminal or OS compatibility issues.
- **Default:** `true`
- **Requires restart:** Yes
- **`ui.hideTips`** (boolean):
- **Description:** Hide helpful tips in the UI
- **Default:** `false`

9
packages/cli/src/config/settingsSchema.ts
View File

@@ -485,6 +485,15 @@ const SETTINGS_SCHEMA = {
'Show a warning when running Gemini CLI in the home directory.',
showInDialog: true,
},
showCompatibilityWarnings: {
type: 'boolean',
label: 'Show Compatibility Warnings',
category: 'UI',
requiresRestart: true,
default: true,
description: 'Show warnings about terminal or OS compatibility issues.',
showInDialog: true,
},
hideTips: {
type: 'boolean',
label: 'Hide Tips',

19
packages/cli/src/ui/components/Notifications.tsx
View File

@@ -88,17 +88,16 @@ export const Notifications = () => {
)}
{updateInfo && <UpdateNotification message={updateInfo.message} />}
{showStartupWarnings && (
<Box
borderStyle="round"
borderColor={theme.status.warning}
paddingX={1}
marginY={1}
flexDirection="column"
>
<Box marginY={1} flexDirection="column">
{startupWarnings.map((warning, index) => (
<Text key={index} color={theme.status.warning}>
{warning}
</Text>
<Box key={index} flexDirection="row">
<Box width={3}>
<Text color={theme.status.warning}>⚠ </Text>
</Box>
<Box flexGrow={1}>
<Text color={theme.status.warning}>{warning}</Text>
</Box>
</Box>
))}
</Box>
)}

28
packages/cli/src/utils/userStartupWarnings.test.ts
View File

@@ -13,6 +13,7 @@ import {
isFolderTrustEnabled,
isWorkspaceTrusted,
} from '../config/trustedFolders.js';
import { getCompatibilityWarnings } from '@google/gemini-cli-core';
// Mock os.homedir to control the home directory in tests
vi.mock('os', async (importOriginal) => {
@@ -29,6 +30,7 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
return {
...actual,
homedir: () => os.homedir(),
getCompatibilityWarnings: vi.fn().mockReturnValue([]),
};
});
@@ -51,11 +53,12 @@ describe('getUserStartupWarnings', () => {
isTrusted: false,
source: undefined,
});
vi.mocked(getCompatibilityWarnings).mockReturnValue([]);
});
afterEach(async () => {
await fs.rm(testRootDir, { recursive: true, force: true });
vi.clearAllMocks();
vi.restoreAllMocks();
});
describe('home directory check', () => {
@@ -135,4 +138,27 @@ describe('getUserStartupWarnings', () => {
expect(warnings).toEqual([expectedWarning, expectedWarning]);
});
});
describe('compatibility warnings', () => {
it('should include compatibility warnings by default', async () => {
vi.mocked(getCompatibilityWarnings).mockReturnValue(['Comp warning 1']);
const projectDir = path.join(testRootDir, 'project');
await fs.mkdir(projectDir);
const warnings = await getUserStartupWarnings({}, projectDir);
expect(warnings).toContain('Comp warning 1');
});
it('should not include compatibility warnings when showCompatibilityWarnings is false', async () => {
vi.mocked(getCompatibilityWarnings).mockReturnValue(['Comp warning 1']);
const projectDir = path.join(testRootDir, 'project');
await fs.mkdir(projectDir);
const warnings = await getUserStartupWarnings(
{ ui: { showCompatibilityWarnings: false } },
projectDir,
);
expect(warnings).not.toContain('Comp warning 1');
});
});
});

10
packages/cli/src/utils/userStartupWarnings.ts
View File

@@ -7,7 +7,7 @@
import fs from 'node:fs/promises';
import path from 'node:path';
import process from 'node:process';
import { homedir } from '@google/gemini-cli-core';
import { homedir, getCompatibilityWarnings } from '@google/gemini-cli-core';
import type { Settings } from '../config/settingsSchema.js';
import {
isFolderTrustEnabled,
@@ -84,5 +84,11 @@ export async function getUserStartupWarnings(
const results = await Promise.all(
WARNING_CHECKS.map((check) => check.check(workspaceRoot, settings)),
);
return results.filter((msg) => msg !== null);
const warnings = results.filter((msg) => msg !== null);
if (settings.ui?.showCompatibilityWarnings !== false) {
warnings.push(...getCompatibilityWarnings());
}
return warnings;
}

1
packages/core/src/index.ts
View File

@@ -180,6 +180,7 @@ export { OAuthUtils } from './mcp/oauth-utils.js';
// Export telemetry functions
export * from './telemetry/index.js';
export { sessionId } from './utils/session.js';
export * from './utils/compatibility.js';
export * from './utils/browser.js';
export { Storage } from './config/storage.js';

156
packages/core/src/utils/compatibility.test.ts Normal file
View File

@@ -0,0 +1,156 @@
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import os from 'node:os';
import {
isWindows10,
isJetBrainsTerminal,
supportsTrueColor,
getCompatibilityWarnings,
} from './compatibility.js';
vi.mock('node:os', () => ({
default: {
platform: vi.fn(),
release: vi.fn(),
},
}));
describe('compatibility', () => {
const originalGetColorDepth = process.stdout.getColorDepth;
afterEach(() => {
process.stdout.getColorDepth = originalGetColorDepth;
vi.restoreAllMocks();
vi.unstubAllEnvs();
});
describe('isWindows10', () => {
it('should return true for Windows 10 (build < 22000)', () => {
vi.mocked(os.platform).mockReturnValue('win32');
vi.mocked(os.release).mockReturnValue('10.0.19041');
expect(isWindows10()).toBe(true);
});
it('should return false for Windows 11 (build >= 22000)', () => {
vi.mocked(os.platform).mockReturnValue('win32');
vi.mocked(os.release).mockReturnValue('10.0.22000');
expect(isWindows10()).toBe(false);
});
it('should return false for non-Windows platforms', () => {
vi.mocked(os.platform).mockReturnValue('darwin');
vi.mocked(os.release).mockReturnValue('20.6.0');
expect(isWindows10()).toBe(false);
});
});
describe('isJetBrainsTerminal', () => {
it('should return true when TERMINAL_EMULATOR is JetBrains-JediTerm', () => {
vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
expect(isJetBrainsTerminal()).toBe(true);
});
it('should return false for other terminals', () => {
vi.stubEnv('TERMINAL_EMULATOR', 'something-else');
expect(isJetBrainsTerminal()).toBe(false);
});
it('should return false when TERMINAL_EMULATOR is not set', () => {
vi.stubEnv('TERMINAL_EMULATOR', '');
expect(isJetBrainsTerminal()).toBe(false);
});
});
describe('supportsTrueColor', () => {
it('should return true when COLORTERM is truecolor', () => {
vi.stubEnv('COLORTERM', 'truecolor');
expect(supportsTrueColor()).toBe(true);
});
it('should return true when COLORTERM is 24bit', () => {
vi.stubEnv('COLORTERM', '24bit');
expect(supportsTrueColor()).toBe(true);
});
it('should return true when getColorDepth returns >= 24', () => {
vi.stubEnv('COLORTERM', '');
process.stdout.getColorDepth = vi.fn().mockReturnValue(24);
expect(supportsTrueColor()).toBe(true);
});
it('should return false when true color is not supported', () => {
vi.stubEnv('COLORTERM', '');
process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
expect(supportsTrueColor()).toBe(false);
});
});
describe('getCompatibilityWarnings', () => {
beforeEach(() => {
// Default to supporting true color to keep existing tests simple
vi.stubEnv('COLORTERM', 'truecolor');
process.stdout.getColorDepth = vi.fn().mockReturnValue(24);
});
it('should return Windows 10 warning when detected', () => {
vi.mocked(os.platform).mockReturnValue('win32');
vi.mocked(os.release).mockReturnValue('10.0.19041');
vi.stubEnv('TERMINAL_EMULATOR', '');
const warnings = getCompatibilityWarnings();
expect(warnings).toContain(
'Warning: Windows 10 detected. Some UI features like smooth scrolling may be degraded. Windows 11 is recommended for the best experience.',
);
});
it('should return JetBrains warning when detected', () => {
vi.mocked(os.platform).mockReturnValue('darwin');
vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
const warnings = getCompatibilityWarnings();
expect(warnings).toContain(
'Warning: JetBrains terminal detected. You may experience rendering or scrolling issues. Using an external terminal (e.g., Windows Terminal, iTerm2) is recommended.',
);
});
it('should return true color warning when not supported', () => {
vi.mocked(os.platform).mockReturnValue('darwin');
vi.stubEnv('TERMINAL_EMULATOR', '');
vi.stubEnv('COLORTERM', '');
process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
const warnings = getCompatibilityWarnings();
expect(warnings).toContain(
'Warning: True color (24-bit) support not detected. Using a terminal with true color enabled will result in a better visual experience.',
);
});
it('should return all warnings when all are detected', () => {
vi.mocked(os.platform).mockReturnValue('win32');
vi.mocked(os.release).mockReturnValue('10.0.19041');
vi.stubEnv('TERMINAL_EMULATOR', 'JetBrains-JediTerm');
vi.stubEnv('COLORTERM', '');
process.stdout.getColorDepth = vi.fn().mockReturnValue(8);
const warnings = getCompatibilityWarnings();
expect(warnings).toHaveLength(3);
expect(warnings[0]).toContain('Windows 10 detected');
expect(warnings[1]).toContain('JetBrains terminal detected');
expect(warnings[2]).toContain('True color (24-bit) support not detected');
});
it('should return no warnings in a standard environment with true color', () => {
vi.mocked(os.platform).mockReturnValue('darwin');
vi.stubEnv('TERMINAL_EMULATOR', '');
vi.stubEnv('COLORTERM', 'truecolor');
const warnings = getCompatibilityWarnings();
expect(warnings).toHaveLength(0);
});
});
});

78
packages/core/src/utils/compatibility.ts Normal file
View File

@@ -0,0 +1,78 @@
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
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') {
return false;
}
const release = os.release();
const parts = release.split('.');
if (parts.length >= 3 && parts[0] === '10' && parts[1] === '0') {
const build = parseInt(parts[2], 10);
return build < 22000;
}
return false;
}
/**
* Detects if the current terminal is a JetBrains-based IDE terminal.
*/
export function isJetBrainsTerminal(): boolean {
return process.env['TERMINAL_EMULATOR'] === 'JetBrains-JediTerm';
}
/**
* Detects if the current terminal supports true color (24-bit).
*/
export function supportsTrueColor(): boolean {
// Check COLORTERM environment variable
if (
process.env['COLORTERM'] === 'truecolor' ||
process.env['COLORTERM'] === '24bit'
) {
return true;
}
// Check if stdout supports 24-bit color depth
if (process.stdout.getColorDepth && process.stdout.getColorDepth() >= 24) {
return true;
}
return false;
}
/**
* Returns a list of compatibility warnings based on the current environment.
*/
export function getCompatibilityWarnings(): string[] {
const warnings: string[] = [];
if (isWindows10()) {
warnings.push(
'Warning: Windows 10 detected. Some UI features like smooth scrolling may be degraded. Windows 11 is recommended for the best experience.',
);
}
if (isJetBrainsTerminal()) {
warnings.push(
'Warning: JetBrains terminal detected. You may experience rendering or scrolling issues. Using an external terminal (e.g., Windows Terminal, iTerm2) is recommended.',
);
}
if (!supportsTrueColor()) {
warnings.push(
'Warning: True color (24-bit) support not detected. Using a terminal with true color enabled will result in a better visual experience.',
);
}
return warnings;
}

7
schemas/settings.schema.json
View File

@@ -262,6 +262,13 @@
"default": true,
"type": "boolean"
},
"showCompatibilityWarnings": {
"title": "Show Compatibility Warnings",
"description": "Show warnings about terminal or OS compatibility issues.",
"markdownDescription": "Show warnings about terminal or OS compatibility issues.\n\n- Category: `UI`\n- Requires restart: `yes`\n- Default: `true`",
"default": true,
"type": "boolean"
},
"hideTips": {
"title": "Hide Tips",
"description": "Hide helpful tips in the UI",