feat(config-xdg): enable XDG conventions

XDG configurations bring flexibility to files previously written only to `~/.gemini directory`.

Author: dbrtly

packages/a2a-server/src/config/extension.ts

@@ -7,17 +7,16 @@
 // Copied exactly from packages/cli/src/config/extension.ts, last PR #1026
 
 import {
-  GEMINI_DIR,
+  Storage,
   type MCPServerConfig,
   type ExtensionInstallMetadata,
   type GeminiCLIExtension,
 } from '@google/gemini-cli-core';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { logger } from '../utils/logger.js';
 
-export const EXTENSIONS_DIRECTORY_NAME = path.join(GEMINI_DIR, 'extensions');
+export const EXTENSIONS_DIRECTORY_NAME = path.join('extensions');
 export const EXTENSIONS_CONFIG_FILENAME = 'gemini-extension.json';
 export const INSTALL_METADATA_FILENAME = '.gemini-extension-install.json';
 
@@ -39,7 +38,7 @@ interface ExtensionConfig {
 export function loadExtensions(workspaceDir: string): GeminiCLIExtension[] {
   const allExtensions = [
     ...loadExtensionsFromDir(workspaceDir),
-    ...loadExtensionsFromDir(os.homedir()),
+    ...loadExtensionsFromDir(Storage.getConfigDir()),
   ];
 
   const uniqueExtensions: GeminiCLIExtension[] = [];

packages/a2a-server/src/config/settings.ts

@@ -6,18 +6,18 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { homedir } from 'node:os';
 
 import type { MCPServerConfig } from '@google/gemini-cli-core';
 import {
   debugLogger,
   GEMINI_DIR,
   getErrorMessage,
+  Storage,
   type TelemetrySettings,
 } from '@google/gemini-cli-core';
 import stripJsonComments from 'strip-json-comments';
 
-export const USER_SETTINGS_DIR = path.join(homedir(), GEMINI_DIR);
+export const USER_SETTINGS_DIR = path.join(Storage.getConfigDir());
 export const USER_SETTINGS_PATH = path.join(USER_SETTINGS_DIR, 'settings.json');
 
 // Reconcile with https://github.com/google-gemini/gemini-cli/blob/b09bc6656080d4d12e1d06734aae2ec33af5c1ed/packages/cli/src/config/settings.ts#L53

packages/cli/src/config/extensions/variables.ts

@@ -4,11 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as path from 'node:path';
 import { type VariableSchema, VARIABLE_SCHEMA } from './variableSchema.js';
-import { GEMINI_DIR } from '@google/gemini-cli-core';
 
-export const EXTENSIONS_DIRECTORY_NAME = path.join(GEMINI_DIR, 'extensions');
+export const EXTENSIONS_DIRECTORY_NAME = 'extensions';
 export const EXTENSIONS_CONFIG_FILENAME = 'gemini-extension.json';
 export const INSTALL_METADATA_FILENAME = '.gemini-extension-install.json';
 export const EXTENSION_SETTINGS_FILENAME = '.env';

packages/cli/src/config/settings.ts

@@ -504,9 +504,13 @@ function findEnvFile(startDir: string): string | null {
     const parentDir = path.dirname(currentDir);
     if (parentDir === currentDir || !parentDir) {
       // check .env under home as fallback, again preferring gemini-specific .env
-      const homeGeminiEnvPath = path.join(homedir(), GEMINI_DIR, '.env');
-      if (fs.existsSync(homeGeminiEnvPath)) {
-        return homeGeminiEnvPath;
+      const userGeminiEnvPath = path.join(
+        Storage.getConfigDir(),
+        GEMINI_DIR,
+        '.env',
+      );
+      if (fs.existsSync(userGeminiEnvPath)) {
+        return userGeminiEnvPath;
       }
       const homeEnvPath = path.join(homedir(), '.env');
       if (fs.existsSync(homeEnvPath)) {

packages/cli/src/config/trustedFolders.ts

@@ -6,28 +6,23 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { homedir } from 'node:os';
 import {
   FatalConfigError,
   getErrorMessage,
   isWithinRoot,
   ideContextStore,
-  GEMINI_DIR,
+  Storage,
 } from '@google/gemini-cli-core';
 import type { Settings } from './settings.js';
 import stripJsonComments from 'strip-json-comments';
 
 export const TRUSTED_FOLDERS_FILENAME = 'trustedFolders.json';
 
-export function getUserSettingsDir(): string {
-  return path.join(homedir(), GEMINI_DIR);
-}
-
 export function getTrustedFoldersPath(): string {
   if (process.env['GEMINI_CLI_TRUSTED_FOLDERS_PATH']) {
     return process.env['GEMINI_CLI_TRUSTED_FOLDERS_PATH'];
   }
-  return path.join(getUserSettingsDir(), TRUSTED_FOLDERS_FILENAME);
+  return path.join(Storage.getConfigDir(), TRUSTED_FOLDERS_FILENAME);
 }
 
 export enum TrustLevel {

packages/cli/src/ui/components/Notifications.tsx

@@ -12,13 +12,12 @@ import { theme } from '../semantic-colors.js';
 import { StreamingState } from '../types.js';
 import { UpdateNotification } from './UpdateNotification.js';
 
-import { GEMINI_DIR, Storage } from '@google/gemini-cli-core';
+import { Storage } from '@google/gemini-cli-core';
 
 import * as fs from 'node:fs/promises';
-import os from 'node:os';
 import path from 'node:path';
 
-const settingsPath = path.join(os.homedir(), GEMINI_DIR, 'settings.json');
+const settingsPath = path.join(Storage.getConfigDir(), 'settings.json');
 
 const screenReaderNudgeFilePath = path.join(
   Storage.getGlobalTempDir(),

packages/cli/src/ui/hooks/useExtensionUpdates.test.tsx

@@ -10,7 +10,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { createExtension } from '../../test-utils/createExtension.js';
 import { useExtensionUpdates } from './useExtensionUpdates.js';
-import { GEMINI_DIR } from '@google/gemini-cli-core';
+import { Storage } from '@google/gemini-cli-core';
 import { render } from '../../test-utils/render.js';
 import { waitFor } from '../../test-utils/async.js';
 import { MessageType } from '../types.js';
@@ -22,6 +22,17 @@ import { ExtensionUpdateState } from '../state/extensions.js';
 import { ExtensionManager } from '../../config/extension-manager.js';
 import { loadSettings } from '../../config/settings.js';
 
+beforeEach(() => {
+  vi.stubEnv('XDG_CONFIG_HOME', '');
+  vi.stubEnv('XDG_CACHE_HOME', '');
+  vi.stubEnv('XDG_DATA_HOME', '');
+  vi.stubEnv('XDG_STATE_HOME', '');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
 vi.mock('os', async (importOriginal) => {
   const mockedOs = await importOriginal<typeof os>();
   return {
@@ -50,7 +61,7 @@ describe('useExtensionUpdates', () => {
       path.join(tempHomeDir, 'gemini-cli-test-workspace-'),
     );
     vi.spyOn(process, 'cwd').mockReturnValue(tempWorkspaceDir);
-    userExtensionsDir = path.join(tempHomeDir, GEMINI_DIR, 'extensions');
+    userExtensionsDir = path.join(Storage.getConfigDir(), 'extensions');
     fs.mkdirSync(userExtensionsDir, { recursive: true });
     vi.mocked(checkForAllExtensionUpdates).mockReset();
     vi.mocked(updateExtension).mockReset();

packages/core/src/code_assist/oauth-credential-storage.ts

@@ -9,9 +9,8 @@ import { HybridTokenStorage } from '../mcp/token-storage/hybrid-token-storage.js
 import { OAUTH_FILE } from '../config/storage.js';
 import type { OAuthCredentials } from '../mcp/token-storage/types.js';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { promises as fs } from 'node:fs';
-import { GEMINI_DIR } from '../utils/paths.js';
+import { Storage } from '../config/storage.js';
 import { coreEvents } from '../utils/events.js';
 
 const KEYCHAIN_SERVICE_NAME = 'gemini-cli-oauth';
@@ -91,7 +90,7 @@ export class OAuthCredentialStorage {
       await this.storage.deleteCredentials(MAIN_ACCOUNT_KEY);
 
       // Also try to remove the old file if it exists
-      const oldFilePath = path.join(os.homedir(), GEMINI_DIR, OAUTH_FILE);
+      const oldFilePath = Storage.getOAuthCredsPath();
       await fs.rm(oldFilePath, { force: true }).catch(() => {});
     } catch (error: unknown) {
       coreEvents.emitFeedback(
@@ -107,7 +106,7 @@ export class OAuthCredentialStorage {
    * Migrate credentials from old file-based storage to keychain
    */
   private static async migrateFromFileStorage(): Promise<Credentials | null> {
-    const oldFilePath = path.join(os.homedir(), GEMINI_DIR, OAUTH_FILE);
+    const oldFilePath = path.join(Storage.getOAuthCredsPath(), OAUTH_FILE);
 
     let credsJson: string;
     try {

packages/core/src/code_assist/oauth2.test.ts

@@ -71,6 +71,7 @@ describe('oauth2', () => {
         path.join(os.tmpdir(), 'gemini-cli-test-home-'),
       );
       vi.mocked(os.homedir).mockReturnValue(tempHomeDir);
+      fs.mkdirSync(path.join(tempHomeDir, GEMINI_DIR), { recursive: true });
     });
     afterEach(() => {
       fs.rmSync(tempHomeDir, { recursive: true, force: true });

packages/core/src/config/storage.test.ts

@@ -4,24 +4,65 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { describe, it, expect, vi } from 'vitest';
-import * as os from 'node:os';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as path from 'node:path';
 
-vi.mock('fs', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('fs')>();
-  return {
-    ...actual,
-    mkdirSync: vi.fn(),
-  };
+const MOCK_GLOBAL_GEMINI_DIR = '/mock/user/home/.gemini';
+const MOCK_CACHE_DIR = '/mock/user/home/.cache/gemini';
+const MOCK_CONFIG_DIR = '/mock/user/home/.config/gemini';
+const MOCK_DATA_DIR = '/mock/user/home/.local/share/gemini';
+
+vi.mock('./storage.js', () => {
+  class MockStorage {
+    private readonly targetDir: string;
+
+    constructor(targetDir: string) {
+      this.targetDir = targetDir;
+    }
+
+    static getGlobalGeminiDir = vi.fn(() => MOCK_GLOBAL_GEMINI_DIR);
+    static getCacheDir = vi.fn(() => MOCK_CACHE_DIR);
+    static getConfigDir = vi.fn(() => MOCK_CONFIG_DIR);
+    static getDataDir = vi.fn(() => MOCK_DATA_DIR);
+    static getMcpOAuthTokensPath = vi.fn(() =>
+      path.join(MOCK_CONFIG_DIR, 'mcp-oauth-tokens.json'),
+    );
+    static getGlobalSettingsPath = vi.fn(() =>
+      path.join(MOCK_CONFIG_DIR, 'settings.json'),
+    );
+    static getUserCommandsDir = vi.fn(() =>
+      path.join(MOCK_CONFIG_DIR, 'commands'),
+    );
+    static getGlobalBinDir = vi.fn(() => path.join(MOCK_CONFIG_DIR, 'bin'));
+    getGeminiDir = () => path.join(this.targetDir, '.gemini');
+    getWorkspaceSettingsPath = () =>
+      path.join(this.getGeminiDir(), 'settings.json');
+    getProjectCommandsDir = () => path.join(this.getGeminiDir(), 'commands');
+  }
+  return { Storage: MockStorage };
 });
 
+beforeEach(() => {
+  vi.stubEnv('XDG_CONFIG_HOME', '');
+  vi.stubEnv('XDG_CACHE_HOME', '');
+  vi.stubEnv('XDG_DATA_HOME', '');
+  vi.stubEnv('XDG_STATE_HOME', '');
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+vi.mock('../utils/paths.js', () => ({
+  GEMINI_DIR: '.gemini',
+}));
+
 import { Storage } from './storage.js';
 import { GEMINI_DIR } from '../utils/paths.js';
 
 describe('Storage – getGlobalSettingsPath', () => {
-  it('returns path to ~/.gemini/settings.json', () => {
-    const expected = path.join(os.homedir(), GEMINI_DIR, 'settings.json');
+  it('returns path to /mock/user/home/.config/gemini/settings.json', () => {
+    const expected = path.join(MOCK_CONFIG_DIR, 'settings.json');
     expect(Storage.getGlobalSettingsPath()).toBe(expected);
   });
 });
@@ -35,8 +76,8 @@ describe('Storage – additional helpers', () => {
     expect(storage.getWorkspaceSettingsPath()).toBe(expected);
   });
 
-  it('getUserCommandsDir returns ~/.gemini/commands', () => {
-    const expected = path.join(os.homedir(), GEMINI_DIR, 'commands');
+  it('getUserCommandsDir returns ~/.config/gemini/commands', () => {
+    const expected = path.join(MOCK_CONFIG_DIR, 'commands');
     expect(Storage.getUserCommandsDir()).toBe(expected);
   });
 
@@ -45,17 +86,13 @@ describe('Storage – additional helpers', () => {
     expect(storage.getProjectCommandsDir()).toBe(expected);
   });
 
-  it('getMcpOAuthTokensPath returns ~/.gemini/mcp-oauth-tokens.json', () => {
-    const expected = path.join(
-      os.homedir(),
-      GEMINI_DIR,
-      'mcp-oauth-tokens.json',
-    );
+  it('getMcpOAuthTokensPath returns ~/.config/gemini/mcp-oauth-tokens.json', () => {
+    const expected = path.join(MOCK_CONFIG_DIR, 'mcp-oauth-tokens.json');
     expect(Storage.getMcpOAuthTokensPath()).toBe(expected);
   });
 
-  it('getGlobalBinDir returns ~/.gemini/tmp/bin', () => {
-    const expected = path.join(os.homedir(), GEMINI_DIR, 'tmp', 'bin');
+  it('getGlobalBinDir returns ~/.config/gemini/bin', () => {
+    const expected = path.join(MOCK_CONFIG_DIR, 'bin');
     expect(Storage.getGlobalBinDir()).toBe(expected);
   });
 });