refactor: refactor settings to a nested structure (#7244)

2025-12-19 09:33:53 +00:00 · 2025-08-27 18:39:45 -07:00
parent b8a7bfd136
commit f22263c9e8
41 changed files with 2852 additions and 1424 deletions
--- a/packages/cli/src/config/settings.ts
+++ b/packages/cli/src/config/settings.ts
@@ -18,6 +18,7 @@ import { DefaultLight } from '../ui/themes/default-light.js';
 import { DefaultDark } from '../ui/themes/default.js';
 import { isWorkspaceTrusted } from './trustedFolders.js';
 import type { Settings, MemoryImportFormat } from './settingsSchema.js';
+import { mergeWith } from 'lodash-es';

 export type { Settings, MemoryImportFormat };

@@ -27,6 +28,58 @@ export const USER_SETTINGS_PATH = Storage.getGlobalSettingsPath();
 export const USER_SETTINGS_DIR = path.dirname(USER_SETTINGS_PATH);
 export const DEFAULT_EXCLUDED_ENV_VARS = ['DEBUG', 'DEBUG_MODE'];

+const MIGRATE_V2_OVERWRITE = false;
+
+// As defined in spec.md
+const MIGRATION_MAP: Record<string, string> = {
+  preferredEditor: 'general.preferredEditor',
+  vimMode: 'general.vimMode',
+  disableAutoUpdate: 'general.disableAutoUpdate',
+  disableUpdateNag: 'general.disableUpdateNag',
+  checkpointing: 'general.checkpointing',
+  theme: 'ui.theme',
+  customThemes: 'ui.customThemes',
+  hideWindowTitle: 'ui.hideWindowTitle',
+  hideTips: 'ui.hideTips',
+  hideBanner: 'ui.hideBanner',
+  hideFooter: 'ui.hideFooter',
+  showMemoryUsage: 'ui.showMemoryUsage',
+  showLineNumbers: 'ui.showLineNumbers',
+  accessibility: 'ui.accessibility',
+  ideMode: 'ide.enabled',
+  hasSeenIdeIntegrationNudge: 'ide.hasSeenNudge',
+  usageStatisticsEnabled: 'privacy.usageStatisticsEnabled',
+  telemetry: 'telemetry',
+  model: 'model.name',
+  maxSessionTurns: 'model.maxSessionTurns',
+  summarizeToolOutput: 'model.summarizeToolOutput',
+  chatCompression: 'model.chatCompression',
+  skipNextSpeakerCheck: 'model.skipNextSpeakerCheck',
+  contextFileName: 'context.fileName',
+  memoryImportFormat: 'context.importFormat',
+  memoryDiscoveryMaxDirs: 'context.discoveryMaxDirs',
+  includeDirectories: 'context.includeDirectories',
+  loadMemoryFromIncludeDirectories: 'context.loadFromIncludeDirectories',
+  fileFiltering: 'context.fileFiltering',
+  sandbox: 'tools.sandbox',
+  shouldUseNodePtyShell: 'tools.usePty',
+  coreTools: 'tools.core',
+  excludeTools: 'tools.exclude',
+  toolDiscoveryCommand: 'tools.discoveryCommand',
+  toolCallCommand: 'tools.callCommand',
+  mcpServerCommand: 'mcp.serverCommand',
+  allowMCPServers: 'mcp.allowed',
+  excludeMCPServers: 'mcp.excluded',
+  folderTrustFeature: 'security.folderTrust.featureEnabled',
+  folderTrust: 'security.folderTrust.enabled',
+  selectedAuthType: 'security.auth.selectedType',
+  useExternalAuth: 'security.auth.useExternal',
+  autoConfigureMaxOldSpaceSize: 'advanced.autoConfigureMemory',
+  dnsResolutionOrder: 'advanced.dnsResolutionOrder',
+  excludedProjectEnvVars: 'advanced.excludedEnvVars',
+  bugCommand: 'advanced.bugCommand',
+};
+
 export function getSystemSettingsPath(): string {
  if (process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH']) {
    return process.env['GEMINI_CLI_SYSTEM_SETTINGS_PATH'];
@@ -82,6 +135,134 @@ export interface SettingsFile {
  path: string;
 }

+function setNestedProperty(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+) {
+  const keys = path.split('.');
+  const lastKey = keys.pop();
+  if (!lastKey) return;
+
+  let current: Record<string, unknown> = obj;
+  for (const key of keys) {
+    if (current[key] === undefined) {
+      current[key] = {};
+    }
+    const next = current[key];
+    if (typeof next === 'object' && next !== null) {
+      current = next as Record<string, unknown>;
+    } else {
+      // This path is invalid, so we stop.
+      return;
+    }
+  }
+  current[lastKey] = value;
+}
+
+function needsMigration(settings: Record<string, unknown>): boolean {
+  return !('general' in settings);
+}
+
+function migrateSettingsToV2(
+  flatSettings: Record<string, unknown>,
+): Record<string, unknown> | null {
+  if (!needsMigration(flatSettings)) {
+    return null;
+  }
+
+  const v2Settings: Record<string, unknown> = {};
+  const flatKeys = new Set(Object.keys(flatSettings));
+
+  for (const [oldKey, newPath] of Object.entries(MIGRATION_MAP)) {
+    if (flatKeys.has(oldKey)) {
+      setNestedProperty(v2Settings, newPath, flatSettings[oldKey]);
+      flatKeys.delete(oldKey);
+    }
+  }
+
+  // Preserve mcpServers at the top level
+  if (flatSettings['mcpServers']) {
+    v2Settings['mcpServers'] = flatSettings['mcpServers'];
+    flatKeys.delete('mcpServers');
+  }
+
+  // Carry over any unrecognized keys
+  for (const remainingKey of flatKeys) {
+    v2Settings[remainingKey] = flatSettings[remainingKey];
+  }
+
+  return v2Settings;
+}
+
+function getNestedProperty(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split('.');
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (typeof current !== 'object' || current === null || !(key in current)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+const REVERSE_MIGRATION_MAP: Record<string, string> = Object.fromEntries(
+  Object.entries(MIGRATION_MAP).map(([key, value]) => [value, key]),
+);
+
+// Dynamically determine the top-level keys from the V2 settings structure.
+const KNOWN_V2_CONTAINERS = new Set(
+  Object.values(MIGRATION_MAP).map((path) => path.split('.')[0]),
+);
+
+export function migrateSettingsToV1(
+  v2Settings: Record<string, unknown>,
+): Record<string, unknown> {
+  const v1Settings: Record<string, unknown> = {};
+  const v2Keys = new Set(Object.keys(v2Settings));
+
+  for (const [newPath, oldKey] of Object.entries(REVERSE_MIGRATION_MAP)) {
+    const value = getNestedProperty(v2Settings, newPath);
+    if (value !== undefined) {
+      v1Settings[oldKey] = value;
+      v2Keys.delete(newPath.split('.')[0]);
+    }
+  }
+
+  // Preserve mcpServers at the top level
+  if (v2Settings['mcpServers']) {
+    v1Settings['mcpServers'] = v2Settings['mcpServers'];
+    v2Keys.delete('mcpServers');
+  }
+
+  // Carry over any unrecognized keys
+  for (const remainingKey of v2Keys) {
+    const value = v2Settings[remainingKey];
+    if (value === undefined) {
+      continue;
+    }
+
+    // Don't carry over empty objects that were just containers for migrated settings.
+    if (
+      KNOWN_V2_CONTAINERS.has(remainingKey) &&
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      Object.keys(value).length === 0
+    ) {
+      continue;
+    }
+
+    v1Settings[remainingKey] = value;
+  }
+
+  return v1Settings;
+}
+
 function mergeSettings(
  system: Settings,
  systemDefaults: Settings,
@@ -92,8 +273,17 @@ function mergeSettings(
  const safeWorkspace = isTrusted ? workspace : ({} as Settings);

  // folderTrust is not supported at workspace level.
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { folderTrust, ...safeWorkspaceWithoutFolderTrust } = safeWorkspace;
+  const { security, ...restOfWorkspace } = safeWorkspace;
+  const safeWorkspaceWithoutFolderTrust = security
+    ? {
+        ...restOfWorkspace,
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        security: (({ folderTrust, ...rest }) => rest)(security),
+      }
+    : {
+        ...restOfWorkspace,
+        security: {},
+      };

  // Settings are merged with the following precedence (last one wins for
  // single values):
@@ -109,40 +299,84 @@ function mergeSettings(
    ...user,
    ...safeWorkspaceWithoutFolderTrust,
    ...system,
-    customThemes: {
-      ...(systemDefaults.customThemes || {}),
-      ...(user.customThemes || {}),
-      ...(safeWorkspace.customThemes || {}),
-      ...(system.customThemes || {}),
+    ui: {
+      ...(systemDefaults.ui || {}),
+      ...(user.ui || {}),
+      ...(safeWorkspaceWithoutFolderTrust.ui || {}),
+      ...(system.ui || {}),
+      customThemes: {
+        ...(systemDefaults.ui?.customThemes || {}),
+        ...(user.ui?.customThemes || {}),
+        ...(safeWorkspaceWithoutFolderTrust.ui?.customThemes || {}),
+        ...(system.ui?.customThemes || {}),
+      },
+    },
+    security: {
+      ...(systemDefaults.security || {}),
+      ...(user.security || {}),
+      ...(safeWorkspaceWithoutFolderTrust.security || {}),
+      ...(system.security || {}),
+    },
+    mcp: {
+      ...(systemDefaults.mcp || {}),
+      ...(user.mcp || {}),
+      ...(safeWorkspaceWithoutFolderTrust.mcp || {}),
+      ...(system.mcp || {}),
    },
    mcpServers: {
      ...(systemDefaults.mcpServers || {}),
      ...(user.mcpServers || {}),
-      ...(safeWorkspace.mcpServers || {}),
+      ...(safeWorkspaceWithoutFolderTrust.mcpServers || {}),
      ...(system.mcpServers || {}),
    },
-    includeDirectories: [
-      ...(systemDefaults.includeDirectories || []),
-      ...(user.includeDirectories || []),
-      ...(safeWorkspace.includeDirectories || []),
-      ...(system.includeDirectories || []),
-    ],
-    chatCompression: {
-      ...(systemDefaults.chatCompression || {}),
-      ...(user.chatCompression || {}),
-      ...(safeWorkspace.chatCompression || {}),
-      ...(system.chatCompression || {}),
+    context: {
+      ...(systemDefaults.context || {}),
+      ...(user.context || {}),
+      ...(safeWorkspaceWithoutFolderTrust.context || {}),
+      ...(system.context || {}),
+      includeDirectories: [
+        ...(systemDefaults.context?.includeDirectories || []),
+        ...(user.context?.includeDirectories || []),
+        ...(safeWorkspaceWithoutFolderTrust.context?.includeDirectories || []),
+        ...(system.context?.includeDirectories || []),
+      ],
+    },
+    model: {
+      ...(systemDefaults.model || {}),
+      ...(user.model || {}),
+      ...(safeWorkspaceWithoutFolderTrust.model || {}),
+      ...(system.model || {}),
+      chatCompression: {
+        ...(systemDefaults.model?.chatCompression || {}),
+        ...(user.model?.chatCompression || {}),
+        ...(safeWorkspaceWithoutFolderTrust.model?.chatCompression || {}),
+        ...(system.model?.chatCompression || {}),
+      },
+    },
+    advanced: {
+      ...(systemDefaults.advanced || {}),
+      ...(user.advanced || {}),
+      ...(safeWorkspaceWithoutFolderTrust.advanced || {}),
+      ...(system.advanced || {}),
+      excludedEnvVars: [
+        ...new Set([
+          ...(systemDefaults.advanced?.excludedEnvVars || []),
+          ...(user.advanced?.excludedEnvVars || []),
+          ...(safeWorkspaceWithoutFolderTrust.advanced?.excludedEnvVars || []),
+          ...(system.advanced?.excludedEnvVars || []),
+        ]),
+      ],
    },
    extensions: {
      ...(systemDefaults.extensions || {}),
      ...(user.extensions || {}),
-      ...(safeWorkspace.extensions || {}),
+      ...(safeWorkspaceWithoutFolderTrust.extensions || {}),
      ...(system.extensions || {}),
      disabled: [
        ...new Set([
          ...(systemDefaults.extensions?.disabled || []),
          ...(user.extensions?.disabled || []),
-          ...(safeWorkspace.extensions?.disabled || []),
+          ...(safeWorkspaceWithoutFolderTrust.extensions?.disabled || []),
          ...(system.extensions?.disabled || []),
        ]),
      ],
@@ -150,7 +384,8 @@ function mergeSettings(
        ...new Set([
          ...(systemDefaults.extensions?.workspacesWithMigrationNudge || []),
          ...(user.extensions?.workspacesWithMigrationNudge || []),
-          ...(safeWorkspace.extensions?.workspacesWithMigrationNudge || []),
+          ...(safeWorkspaceWithoutFolderTrust.extensions
+            ?.workspacesWithMigrationNudge || []),
          ...(system.extensions?.workspacesWithMigrationNudge || []),
        ]),
      ],
@@ -166,6 +401,7 @@ export class LoadedSettings {
    workspace: SettingsFile,
    errors: SettingsError[],
    isTrusted: boolean,
+    migratedInMemorScopes: Set<SettingScope>,
  ) {
    this.system = system;
    this.systemDefaults = systemDefaults;
@@ -173,6 +409,7 @@ export class LoadedSettings {
    this.workspace = workspace;
    this.errors = errors;
    this.isTrusted = isTrusted;
+    this.migratedInMemorScopes = migratedInMemorScopes;
    this._merged = this.computeMergedSettings();
  }

@@ -182,6 +419,7 @@ export class LoadedSettings {
  readonly workspace: SettingsFile;
  readonly errors: SettingsError[];
  readonly isTrusted: boolean;
+  readonly migratedInMemorScopes: Set<SettingScope>;

  private _merged: Settings;

@@ -214,13 +452,9 @@ export class LoadedSettings {
    }
  }

-  setValue<K extends keyof Settings>(
-    scope: SettingScope,
-    key: K,
-    value: Settings[K],
-  ): void {
+  setValue(scope: SettingScope, key: string, value: unknown): void {
    const settingsFile = this.forScope(scope);
-    settingsFile.settings[key] = value;
+    setNestedProperty(settingsFile.settings, key, value);
    this._merged = this.computeMergedSettings();
    saveSettings(settingsFile);
  }
@@ -357,7 +591,8 @@ export function loadEnvironment(settings?: Settings): void {
      const parsedEnv = dotenv.parse(envFileContent);

      const excludedVars =
-        resolvedSettings?.excludedProjectEnvVars || DEFAULT_EXCLUDED_ENV_VARS;
+        resolvedSettings?.advanced?.excludedEnvVars ||
+        DEFAULT_EXCLUDED_ENV_VARS;
      const isProjectEnvFile = !envFilePath.includes(GEMINI_DIR);

      for (const key in parsedEnv) {
@@ -391,6 +626,7 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
  const settingsErrors: SettingsError[] = [];
  const systemSettingsPath = getSystemSettingsPath();
  const systemDefaultsPath = getSystemDefaultsPath();
+  const migratedInMemorScopes = new Set<SettingScope>();

  // Resolve paths to their canonical representation to handle symlinks
  const resolvedWorkspaceDir = path.resolve(workspaceDir);
@@ -411,85 +647,97 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
    workspaceDir,
  ).getWorkspaceSettingsPath();

-  // Load system settings
-  try {
-    if (fs.existsSync(systemSettingsPath)) {
-      const systemContent = fs.readFileSync(systemSettingsPath, 'utf-8');
-      systemSettings = JSON.parse(stripJsonComments(systemContent)) as Settings;
-    }
-  } catch (error: unknown) {
-    settingsErrors.push({
-      message: getErrorMessage(error),
-      path: systemSettingsPath,
-    });
-  }
-
-  // Load system defaults
-  try {
-    if (fs.existsSync(systemDefaultsPath)) {
-      const systemDefaultsContent = fs.readFileSync(
-        systemDefaultsPath,
-        'utf-8',
-      );
-      const parsedSystemDefaults = JSON.parse(
-        stripJsonComments(systemDefaultsContent),
-      ) as Settings;
-      systemDefaultSettings = resolveEnvVarsInObject(parsedSystemDefaults);
-    }
-  } catch (error: unknown) {
-    settingsErrors.push({
-      message: getErrorMessage(error),
-      path: systemDefaultsPath,
-    });
-  }
-
-  // Load user settings
-  try {
-    if (fs.existsSync(USER_SETTINGS_PATH)) {
-      const userContent = fs.readFileSync(USER_SETTINGS_PATH, 'utf-8');
-      userSettings = JSON.parse(stripJsonComments(userContent)) as Settings;
-      // Support legacy theme names
-      if (userSettings.theme && userSettings.theme === 'VS') {
-        userSettings.theme = DefaultLight.name;
-      } else if (userSettings.theme && userSettings.theme === 'VS2015') {
-        userSettings.theme = DefaultDark.name;
-      }
-    }
-  } catch (error: unknown) {
-    settingsErrors.push({
-      message: getErrorMessage(error),
-      path: USER_SETTINGS_PATH,
-    });
-  }
-
-  if (realWorkspaceDir !== realHomeDir) {
-    // Load workspace settings
+  const loadAndMigrate = (filePath: string, scope: SettingScope): Settings => {
    try {
-      if (fs.existsSync(workspaceSettingsPath)) {
-        const projectContent = fs.readFileSync(workspaceSettingsPath, 'utf-8');
-        workspaceSettings = JSON.parse(
-          stripJsonComments(projectContent),
-        ) as Settings;
-        if (workspaceSettings.theme && workspaceSettings.theme === 'VS') {
-          workspaceSettings.theme = DefaultLight.name;
-        } else if (
-          workspaceSettings.theme &&
-          workspaceSettings.theme === 'VS2015'
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const rawSettings: unknown = JSON.parse(stripJsonComments(content));
+
+        if (
+          typeof rawSettings !== 'object' ||
+          rawSettings === null ||
+          Array.isArray(rawSettings)
        ) {
-          workspaceSettings.theme = DefaultDark.name;
+          settingsErrors.push({
+            message: 'Settings file is not a valid JSON object.',
+            path: filePath,
+          });
+          return {};
        }
+
+        let settingsObject = rawSettings as Record<string, unknown>;
+        if (needsMigration(settingsObject)) {
+          console.error(`Legacy settings file detected at: ${filePath}`);
+          const migratedSettings = migrateSettingsToV2(settingsObject);
+          if (migratedSettings) {
+            if (MIGRATE_V2_OVERWRITE) {
+              try {
+                fs.renameSync(filePath, `${filePath}.orig`);
+                fs.writeFileSync(
+                  filePath,
+                  JSON.stringify(migratedSettings, null, 2),
+                  'utf-8',
+                );
+                console.log(
+                  `Successfully migrated and saved settings file: ${filePath}`,
+                );
+              } catch (e) {
+                console.error(
+                  `Error migrating settings file on disk: ${getErrorMessage(
+                    e,
+                  )}`,
+                );
+              }
+            } else {
+              console.log(
+                `Successfully migrated settings for ${filePath} in-memory for the current session.`,
+              );
+              migratedInMemorScopes.add(scope);
+            }
+            settingsObject = migratedSettings;
+          }
+        }
+        return settingsObject as Settings;
      }
    } catch (error: unknown) {
      settingsErrors.push({
        message: getErrorMessage(error),
-        path: workspaceSettingsPath,
+        path: filePath,
      });
    }
+    return {};
+  };
+
+  systemSettings = loadAndMigrate(systemSettingsPath, SettingScope.System);
+  systemDefaultSettings = loadAndMigrate(
+    systemDefaultsPath,
+    SettingScope.SystemDefaults,
+  );
+  userSettings = loadAndMigrate(USER_SETTINGS_PATH, SettingScope.User);
+
+  if (realWorkspaceDir !== realHomeDir) {
+    workspaceSettings = loadAndMigrate(
+      workspaceSettingsPath,
+      SettingScope.Workspace,
+    );
+  }
+
+  // Support legacy theme names
+  if (userSettings.ui?.theme === 'VS') {
+    userSettings.ui.theme = DefaultLight.name;
+  } else if (userSettings.ui?.theme === 'VS2015') {
+    userSettings.ui.theme = DefaultDark.name;
+  }
+  if (workspaceSettings.ui?.theme === 'VS') {
+    workspaceSettings.ui.theme = DefaultLight.name;
+  } else if (workspaceSettings.ui?.theme === 'VS2015') {
+    workspaceSettings.ui.theme = DefaultDark.name;
  }

  // For the initial trust check, we can only use user and system settings.
-  const initialTrustCheckSettings = { ...systemSettings, ...userSettings };
-  const isTrusted = isWorkspaceTrusted(initialTrustCheckSettings) ?? true;
+  const initialTrustCheckSettings = mergeWith({}, systemSettings, userSettings);
+  const isTrusted =
+    isWorkspaceTrusted(initialTrustCheckSettings as Settings) ?? true;

  // Create a temporary merged settings object to pass to loadEnvironment.
  const tempMergedSettings = mergeSettings(
@@ -529,21 +777,9 @@ export function loadSettings(workspaceDir: string): LoadedSettings {
    },
    settingsErrors,
    isTrusted,
+    migratedInMemorScopes,
  );

-  // Validate chatCompression settings
-  const chatCompression = loadedSettings.merged.chatCompression;
-  const threshold = chatCompression?.contextPercentageThreshold;
-  if (
-    threshold != null &&
-    (typeof threshold !== 'number' || threshold < 0 || threshold > 1)
-  ) {
-    console.warn(
-      `Invalid value for chatCompression.contextPercentageThreshold: "${threshold}". Please use a value between 0 and 1. Using default compression settings.`,
-    );
-    delete loadedSettings.merged.chatCompression;
-  }
-
  return loadedSettings;
 }

@@ -555,9 +791,16 @@ export function saveSettings(settingsFile: SettingsFile): void {
      fs.mkdirSync(dirPath, { recursive: true });
    }

+    let settingsToSave = settingsFile.settings;
+    if (!MIGRATE_V2_OVERWRITE) {
+      settingsToSave = migrateSettingsToV1(
+        settingsToSave as Record<string, unknown>,
+      ) as Settings;
+    }
+
    fs.writeFileSync(
      settingsFile.path,
-      JSON.stringify(settingsFile.settings, null, 2),
+      JSON.stringify(settingsToSave, null, 2),
      'utf-8',
    );
  } catch (error) {