refactor(a2a-server): implement V1 to V2 settings migration logic - #29450

Summary

This change updates the configuration loader in packages/a2a-server
(src/config/settings.ts and src/config/config.ts) to support the
hierarchical V2 configuration schema while preserving transparent in-memory
backward compatibility with flat V1 settings files.

From an architectural perspective, this unifies the configuration processing
pipeline between @google/gemini-cli and @google/gemini-cli-a2a-server by
introducing in-memory key normalization (migrateDeprecatedSettings), recursive
multi-scope object merging (customDeepMerge), recursive environment variable
interpolation (resolveEnvVarsInObject), and deterministic schema validation
(validateSettings / settingsZodSchema).

Details

• In-Memory V1-to-V2 Configuration Normalization
  (migrateDeprecatedSettings):
  • Mapped legacy flat V1 configuration keys (MIGRATION_MAP) and inverted
    boolean flags (such as telemetryDisabled $\rightarrow$
    telemetry.enabled, logLevel $\rightarrow$ logging.level, coreTools
    $\rightarrow$ tools.core, excludeTools $\rightarrow$ tools.exclude,
    allowedTools $\rightarrow$ tools.allowed, folderTrust $\rightarrow$
    security.folderTrust.enabled, showMemoryUsage $\rightarrow$
    ui.showMemoryUsage, checkpointing $\rightarrow$ general.checkpointing,
    and fileFiltering $\rightarrow$ context.fileFiltering) into their
    corresponding V2 nested structure in memory without modifying user
    configuration files on disk.
  • Added non-enumerable compatibility accessors on the resolved Settings
    object and updated loadConfig / setIsTrusted in
    packages/a2a-server/src/config/config.ts to read canonical V2 paths with
    fallback support.
• Recursive Multi-Scope Merging (customDeepMerge):
  • Replaced shallow top-level object spreading
    ({ ...userSettings, ...workspaceSettings }) with customDeepMerge so
    workspace-scoped nested settings merge cleanly with user-scoped nested
    settings without discarding sibling properties.
  • Filtered reserved object prototype keys (__proto__, constructor,
    prototype) during recursive merging and environment resolution to ensure
    deterministic object construction.
• Recursive Environment Variable Interpolation (resolveEnvVarsInObject):
  • Updated resolveEnvVarsInString and resolveEnvVarsInObject to support
    $VAR, ${VAR}, and ${VAR:-default} syntax across nested V2 objects and
    arrays with WeakSet circular-reference tracking.
• Deterministic V2 Schema Validation (validateSettings /
  settingsZodSchema):
  • Added Zod schema validation (settingsZodSchema) for V2 configuration
    sections and validated normalized settings during configuration loading.
• Unit Test Coverage:
  • Added automated unit tests in
    packages/a2a-server/src/config/settings.test.ts,
    packages/a2a-server/src/config/config.test.ts, and
    packages/a2a-server/src/http/app.test.ts verifying V1-to-V2 in-memory
    conversion and Zod schema validation, V2 structure preservation and deep
    merging across scopes, reserved key filtering in customDeepMerge, nested
    environment variable interpolation, and V1/V2 settings handling in
    loadConfig, setIsTrusted, and createApp.

Related Issues

fixes: GH-28261

How to Validate

1. Run the targeted unit test suites added for V1-to-V2 settings migration, config loading, and HTTP server bootstrap:
   ```bash
   npm test -w @google/gemini-cli-a2a-server -- src/config/settings.test.ts src/config/config.test.ts src/http/app.test.ts

• Expected result: All 3 test files (63/63 tests) pass, verifying:
• src/config/settings.test.ts (12/12 tests):
• 100% legacy V1 flat settings (telemetryDisabled, logLevel, coreTools, excludeTools, allowedTools, folderTrust,
showMemoryUsage, checkpointing, fileFiltering) are migrated in memory to V2 nested properties (telemetry.enabled,
logging.level, tools.*, security.folderTrust.enabled, ui.showMemoryUsage, general.checkpointing, context.fileFiltering)
without modifying settings.json on disk, and pass Zod V2 schema validation (validateSettings).
• 100% V2 nested settings preserve their structure and deep-merge across User and Workspace scopes via customDeepMerge
without overwriting sibling properties.
• Edge cases: customDeepMerge and resolveEnvVarsInObject filter out proto, constructor, and prototype keys
(prototype pollution protection), handle circular references via WeakSet, and recursively interpolate $VAR, ${VAR}, and
${VAR:-default} across nested objects and arrays.
• src/config/config.test.ts (30/30 tests):
• loadConfig() and setIsTrusted() read canonical V2 settings (security.folderTrust.enabled, general.checkpointing.
enabled, ui.showMemoryUsage, context.fileFiltering, logging.level) while maintaining fallback support for unmigrated V1
objects and preserving environment variable overrides (GEMINI_FOLDER_TRUST, CHECKPOINTING, CUSTOM_IGNORE_FILE_PATHS,
GEMINI_CLI_TRUST_WORKSPACE).
• src/http/app.test.ts (21/21 tests):
• createApp() reads V2 security.folderTrust.enabled from loadSettings() during initial HTTP server startup.
2. Run the full @google/gemini-cli-a2a-server package test suite and repository preflight:
npm test -w @google/gemini-cli-a2a-server
npm run preflight

  • Expected result: All 16/16 test files (164/164 tests) in @google/gemini-cli-a2a-server and the full workspace preflight
  (clean, install, build, lint, typecheck, and all workspace test suites) pass with 0 errors.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• [ x] Added/updated tests (if needed)
• Noted breaking changes (if any)
• [ x] Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • [ x] Linux
    • [ x] npm run
    • npx
    • Docker