feat(ui): improve startup warnings UX with dismissal and show-count limits (#19584)

packages/cli/src/utils/persistentState.ts

@@ -15,6 +15,7 @@ interface PersistentStateData {
   tipsShown?: number;
   hasSeenScreenReaderNudge?: boolean;
   focusUiEnabled?: boolean;
+  startupWarningCounts?: Record<string, number>;
   // Add other persistent state keys here as needed
 }
 

packages/cli/src/utils/userStartupWarnings.test.ts

@@ -13,7 +13,10 @@ import {
   isFolderTrustEnabled,
   isWorkspaceTrusted,
 } from '../config/trustedFolders.js';
-import { getCompatibilityWarnings } from '@google/gemini-cli-core';
+import {
+  getCompatibilityWarnings,
+  WarningPriority,
+} from '@google/gemini-cli-core';
 
 // Mock os.homedir to control the home directory in tests
 vi.mock('os', async (importOriginal) => {
@@ -31,6 +34,10 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
     ...actual,
     homedir: () => os.homedir(),
     getCompatibilityWarnings: vi.fn().mockReturnValue([]),
+    WarningPriority: {
+      Low: 'low',
+      High: 'high',
+    },
   };
 });
 
@@ -65,12 +72,13 @@ describe('getUserStartupWarnings', () => {
     it('should return a warning when running in home directory', async () => {
       const warnings = await getUserStartupWarnings({}, homeDir);
       expect(warnings).toContainEqual(
-        expect.stringContaining(
-          'Warning you are running Gemini CLI in your home directory',
-        ),
-      );
-      expect(warnings).toContainEqual(
-        expect.stringContaining('warning can be disabled in /settings'),
+        expect.objectContaining({
+          id: 'home-directory',
+          message: expect.stringContaining(
+            'Warning you are running Gemini CLI in your home directory',
+          ),
+          priority: WarningPriority.Low,
+        }),
       );
     });
 
@@ -78,9 +86,7 @@ describe('getUserStartupWarnings', () => {
       const projectDir = path.join(testRootDir, 'project');
       await fs.mkdir(projectDir);
       const warnings = await getUserStartupWarnings({}, projectDir);
-      expect(warnings).not.toContainEqual(
-        expect.stringContaining('home directory'),
-      );
+      expect(warnings.find((w) => w.id === 'home-directory')).toBeUndefined();
     });
 
     it('should not return a warning when showHomeDirectoryWarning is false', async () => {
@@ -88,9 +94,7 @@ describe('getUserStartupWarnings', () => {
         { ui: { showHomeDirectoryWarning: false } },
         homeDir,
       );
-      expect(warnings).not.toContainEqual(
-        expect.stringContaining('home directory'),
-      );
+      expect(warnings.find((w) => w.id === 'home-directory')).toBeUndefined();
     });
 
     it('should not return a warning when folder trust is enabled and workspace is trusted', async () => {
@@ -101,9 +105,7 @@ describe('getUserStartupWarnings', () => {
       });
 
       const warnings = await getUserStartupWarnings({}, homeDir);
-      expect(warnings).not.toContainEqual(
-        expect.stringContaining('home directory'),
-      );
+      expect(warnings.find((w) => w.id === 'home-directory')).toBeUndefined();
     });
   });
 
@@ -112,10 +114,11 @@ describe('getUserStartupWarnings', () => {
       const rootDir = path.parse(testRootDir).root;
       const warnings = await getUserStartupWarnings({}, rootDir);
       expect(warnings).toContainEqual(
-        expect.stringContaining('root directory'),
-      );
-      expect(warnings).toContainEqual(
-        expect.stringContaining('folder structure will be used'),
+        expect.objectContaining({
+          id: 'root-directory',
+          message: expect.stringContaining('root directory'),
+          priority: WarningPriority.High,
+        }),
       );
     });
 
@@ -123,9 +126,7 @@ describe('getUserStartupWarnings', () => {
       const projectDir = path.join(testRootDir, 'project');
       await fs.mkdir(projectDir);
       const warnings = await getUserStartupWarnings({}, projectDir);
-      expect(warnings).not.toContainEqual(
-        expect.stringContaining('root directory'),
-      );
+      expect(warnings.find((w) => w.id === 'root-directory')).toBeUndefined();
     });
   });
 
@@ -133,24 +134,37 @@ describe('getUserStartupWarnings', () => {
     it('should handle errors when checking directory', async () => {
       const nonExistentPath = path.join(testRootDir, 'non-existent');
       const warnings = await getUserStartupWarnings({}, nonExistentPath);
-      const expectedWarning =
+      const expectedMessage =
         'Could not verify the current directory due to a file system error.';
-      expect(warnings).toEqual([expectedWarning, expectedWarning]);
+      expect(warnings).toEqual([
+        expect.objectContaining({ message: expectedMessage }),
+        expect.objectContaining({ message: expectedMessage }),
+      ]);
     });
   });
 
   describe('compatibility warnings', () => {
     it('should include compatibility warnings by default', async () => {
-      vi.mocked(getCompatibilityWarnings).mockReturnValue(['Comp warning 1']);
+      const compWarning = {
+        id: 'comp-1',
+        message: 'Comp warning 1',
+        priority: WarningPriority.High,
+      };
+      vi.mocked(getCompatibilityWarnings).mockReturnValue([compWarning]);
       const projectDir = path.join(testRootDir, 'project');
       await fs.mkdir(projectDir);
 
       const warnings = await getUserStartupWarnings({}, projectDir);
-      expect(warnings).toContain('Comp warning 1');
+      expect(warnings).toContainEqual(compWarning);
     });
 
     it('should not include compatibility warnings when showCompatibilityWarnings is false', async () => {
-      vi.mocked(getCompatibilityWarnings).mockReturnValue(['Comp warning 1']);
+      const compWarning = {
+        id: 'comp-1',
+        message: 'Comp warning 1',
+        priority: WarningPriority.High,
+      };
+      vi.mocked(getCompatibilityWarnings).mockReturnValue([compWarning]);
       const projectDir = path.join(testRootDir, 'project');
       await fs.mkdir(projectDir);
 
@@ -158,7 +172,7 @@ describe('getUserStartupWarnings', () => {
         { ui: { showCompatibilityWarnings: false } },
         projectDir,
       );
-      expect(warnings).not.toContain('Comp warning 1');
+      expect(warnings).not.toContainEqual(compWarning);
     });
   });
 });

packages/cli/src/utils/userStartupWarnings.ts

@@ -7,7 +7,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
-import { homedir, getCompatibilityWarnings } from '@google/gemini-cli-core';
+import {
+  homedir,
+  getCompatibilityWarnings,
+  WarningPriority,
+  type StartupWarning,
+} from '@google/gemini-cli-core';
 import type { Settings } from '../config/settingsSchema.js';
 import {
   isFolderTrustEnabled,
@@ -17,11 +22,13 @@ import {
 type WarningCheck = {
   id: string;
   check: (workspaceRoot: string, settings: Settings) => Promise<string | null>;
+  priority: WarningPriority;
 };
 
 // Individual warning checks
 const homeDirectoryCheck: WarningCheck = {
   id: 'home-directory',
+  priority: WarningPriority.Low,
   check: async (workspaceRoot: string, settings: Settings) => {
     if (settings.ui?.showHomeDirectoryWarning === false) {
       return null;
@@ -53,6 +60,7 @@ const homeDirectoryCheck: WarningCheck = {
 
 const rootDirectoryCheck: WarningCheck = {
   id: 'root-directory',
+  priority: WarningPriority.High,
   check: async (workspaceRoot: string, _settings: Settings) => {
     try {
       const workspaceRealPath = await fs.realpath(workspaceRoot);
@@ -80,11 +88,21 @@ const WARNING_CHECKS: readonly WarningCheck[] = [
 export async function getUserStartupWarnings(
   settings: Settings,
   workspaceRoot: string = process.cwd(),
-): Promise<string[]> {
+): Promise<StartupWarning[]> {
   const results = await Promise.all(
-    WARNING_CHECKS.map((check) => check.check(workspaceRoot, settings)),
+    WARNING_CHECKS.map(async (check) => {
+      const message = await check.check(workspaceRoot, settings);
+      if (message) {
+        return {
+          id: check.id,
+          message,
+          priority: check.priority,
+        };
+      }
+      return null;
+    }),
   );
-  const warnings = results.filter((msg) => msg !== null);
+  const warnings = results.filter((w): w is StartupWarning => w !== null);
 
   if (settings.ui?.showCompatibilityWarnings !== false) {
     warnings.push(...getCompatibilityWarnings());