@aetherai/aether 0.0.8 → 0.0.10

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2-shared.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Structural mapping table for V1 -> V2.
+ *
+ * Used by:
+ * - v1->v2 migration execution
+ * - warnings for residual legacy keys in latest-version settings files
+ */
+export declare const V1_TO_V2_MIGRATION_MAP: Record<string, string>;
+/**
+ * Top-level keys that are V2/V3 containers.
+ * If one of these keys already has object value, treat it as latest-format data.
+ */
+export declare const V2_CONTAINER_KEYS: Set<string>;
+/**
+ * Legacy disable* keys that remain in disable* form for V2.
+ */
+export declare const V1_TO_V2_PRESERVE_DISABLE_MAP: Record<string, string>;
+export declare const CONSOLIDATED_DISABLE_KEYS: Set<string>;
+/**
+ * Keys that indicate V1-like top-level structure when holding primitive values.
+ */
+export declare const V1_INDICATOR_KEYS: string[];

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2-shared.js

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Structural mapping table for V1 -> V2.
+ *
+ * Used by:
+ * - v1->v2 migration execution
+ * - warnings for residual legacy keys in latest-version settings files
+ */
+export const V1_TO_V2_MIGRATION_MAP = {
+    accessibility: 'ui.accessibility',
+    allowedTools: 'tools.allowed',
+    allowMCPServers: 'mcp.allowed',
+    autoAccept: 'tools.autoAccept',
+    autoConfigureMaxOldSpaceSize: 'advanced.autoConfigureMemory',
+    bugCommand: 'advanced.bugCommand',
+    chatCompression: 'model.chatCompression',
+    checkpointing: 'general.checkpointing',
+    coreTools: 'tools.core',
+    contextFileName: 'context.fileName',
+    customThemes: 'ui.customThemes',
+    customWittyPhrases: 'ui.customWittyPhrases',
+    debugKeystrokeLogging: 'general.debugKeystrokeLogging',
+    dnsResolutionOrder: 'advanced.dnsResolutionOrder',
+    enforcedAuthType: 'security.auth.enforcedType',
+    excludeTools: 'tools.exclude',
+    excludeMCPServers: 'mcp.excluded',
+    excludedProjectEnvVars: 'advanced.excludedEnvVars',
+    extensions: 'extensions',
+    fileFiltering: 'context.fileFiltering',
+    folderTrustFeature: 'security.folderTrust.featureEnabled',
+    folderTrust: 'security.folderTrust.enabled',
+    hasSeenIdeIntegrationNudge: 'ide.hasSeenNudge',
+    hideWindowTitle: 'ui.hideWindowTitle',
+    showStatusInTitle: 'ui.showStatusInTitle',
+    hideTips: 'ui.hideTips',
+    showLineNumbers: 'ui.showLineNumbers',
+    showCitations: 'ui.showCitations',
+    ideMode: 'ide.enabled',
+    includeDirectories: 'context.includeDirectories',
+    loadMemoryFromIncludeDirectories: 'context.loadFromIncludeDirectories',
+    maxSessionTurns: 'model.maxSessionTurns',
+    mcpServers: 'mcpServers',
+    mcpServerCommand: 'mcp.serverCommand',
+    memoryImportFormat: 'context.importFormat',
+    model: 'model.name',
+    preferredEditor: 'general.preferredEditor',
+    sandbox: 'tools.sandbox',
+    selectedAuthType: 'security.auth.selectedType',
+    shouldUseNodePtyShell: 'tools.shell.enableInteractiveShell',
+    shellPager: 'tools.shell.pager',
+    shellShowColor: 'tools.shell.showColor',
+    skipNextSpeakerCheck: 'model.skipNextSpeakerCheck',
+    telemetry: 'telemetry',
+    theme: 'ui.theme',
+    toolDiscoveryCommand: 'tools.discoveryCommand',
+    toolCallCommand: 'tools.callCommand',
+    usageStatisticsEnabled: 'privacy.usageStatisticsEnabled',
+    useExternalAuth: 'security.auth.useExternal',
+    useRipgrep: 'tools.useRipgrep',
+    vimMode: 'general.vimMode',
+    enableWelcomeBack: 'ui.enableWelcomeBack',
+    approvalMode: 'tools.approvalMode',
+    sessionTokenLimit: 'model.sessionTokenLimit',
+    contentGenerator: 'model.generationConfig',
+    skipLoopDetection: 'model.skipLoopDetection',
+    skipStartupContext: 'model.skipStartupContext',
+    enableOpenAILogging: 'model.enableOpenAILogging',
+    tavilyApiKey: 'advanced.tavilyApiKey',
+};
+/**
+ * Top-level keys that are V2/V3 containers.
+ * If one of these keys already has object value, treat it as latest-format data.
+ */
+export const V2_CONTAINER_KEYS = new Set([
+    'ui',
+    'tools',
+    'mcp',
+    'advanced',
+    'model',
+    'general',
+    'context',
+    'security',
+    'ide',
+    'privacy',
+    'telemetry',
+    'extensions',
+]);
+/**
+ * Legacy disable* keys that remain in disable* form for V2.
+ */
+export const V1_TO_V2_PRESERVE_DISABLE_MAP = {
+    disableAutoUpdate: 'general.disableAutoUpdate',
+    disableUpdateNag: 'general.disableUpdateNag',
+    disableLoadingPhrases: 'ui.accessibility.disableLoadingPhrases',
+    disableFuzzySearch: 'context.fileFiltering.disableFuzzySearch',
+    disableCacheControl: 'model.generationConfig.disableCacheControl',
+};
+export const CONSOLIDATED_DISABLE_KEYS = new Set([
+    'disableAutoUpdate',
+    'disableUpdateNag',
+]);
+/**
+ * Keys that indicate V1-like top-level structure when holding primitive values.
+ */
+export const V1_INDICATOR_KEYS = [
+    // From V1_TO_V2_MIGRATION_MAP - keys that map to different paths in V2
+    'theme',
+    'model',
+    'autoAccept',
+    'hideTips',
+    'vimMode',
+    'checkpointing',
+    'accessibility',
+    'allowedTools',
+    'allowMCPServers',
+    'autoConfigureMaxOldSpaceSize',
+    'bugCommand',
+    'chatCompression',
+    'coreTools',
+    'contextFileName',
+    'customThemes',
+    'customWittyPhrases',
+    'debugKeystrokeLogging',
+    'dnsResolutionOrder',
+    'enforcedAuthType',
+    'excludeTools',
+    'excludeMCPServers',
+    'excludedProjectEnvVars',
+    'fileFiltering',
+    'folderTrustFeature',
+    'folderTrust',
+    'hasSeenIdeIntegrationNudge',
+    'hideWindowTitle',
+    'showStatusInTitle',
+    'showLineNumbers',
+    'showCitations',
+    'ideMode',
+    'includeDirectories',
+    'loadMemoryFromIncludeDirectories',
+    'maxSessionTurns',
+    'mcpServerCommand',
+    'memoryImportFormat',
+    'preferredEditor',
+    'sandbox',
+    'selectedAuthType',
+    'shouldUseNodePtyShell',
+    'shellPager',
+    'shellShowColor',
+    'skipNextSpeakerCheck',
+    'toolDiscoveryCommand',
+    'toolCallCommand',
+    'usageStatisticsEnabled',
+    'useExternalAuth',
+    'useRipgrep',
+    'enableWelcomeBack',
+    'approvalMode',
+    'sessionTokenLimit',
+    'contentGenerator',
+    'skipLoopDetection',
+    'skipStartupContext',
+    'enableOpenAILogging',
+    'tavilyApiKey',
+    // From V1_TO_V2_PRESERVE_DISABLE_MAP - disable* keys that get nested in V2
+    'disableAutoUpdate',
+    'disableUpdateNag',
+    'disableLoadingPhrases',
+    'disableFuzzySearch',
+    'disableCacheControl',
+];
+//# sourceMappingURL=v1-to-v2-shared.js.map

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1-to-v2-shared.js","sourceRoot":"","sources":["../../../../../../../../src/config/migration/versions/v1-to-v2-shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,aAAa,EAAE,kBAAkB;IACjC,YAAY,EAAE,eAAe;IAC7B,eAAe,EAAE,aAAa;IAC9B,UAAU,EAAE,kBAAkB;IAC9B,4BAA4B,EAAE,8BAA8B;IAC5D,UAAU,EAAE,qBAAqB;IACjC,eAAe,EAAE,uBAAuB;IACxC,aAAa,EAAE,uBAAuB;IACtC,SAAS,EAAE,YAAY;IACvB,eAAe,EAAE,kBAAkB;IACnC,YAAY,EAAE,iBAAiB;IAC/B,kBAAkB,EAAE,uBAAuB;IAC3C,qBAAqB,EAAE,+BAA+B;IACtD,kBAAkB,EAAE,6BAA6B;IACjD,gBAAgB,EAAE,4BAA4B;IAC9C,YAAY,EAAE,eAAe;IAC7B,iBAAiB,EAAE,cAAc;IACjC,sBAAsB,EAAE,0BAA0B;IAClD,UAAU,EAAE,YAAY;IACxB,aAAa,EAAE,uBAAuB;IACtC,kBAAkB,EAAE,qCAAqC;IACzD,WAAW,EAAE,8BAA8B;IAC3C,0BAA0B,EAAE,kBAAkB;IAC9C,eAAe,EAAE,oBAAoB;IACrC,iBAAiB,EAAE,sBAAsB;IACzC,QAAQ,EAAE,aAAa;IACvB,eAAe,EAAE,oBAAoB;IACrC,aAAa,EAAE,kBAAkB;IACjC,OAAO,EAAE,aAAa;IACtB,kBAAkB,EAAE,4BAA4B;IAChD,gCAAgC,EAAE,oCAAoC;IACtE,eAAe,EAAE,uBAAuB;IACxC,UAAU,EAAE,YAAY;IACxB,gBAAgB,EAAE,mBAAmB;IACrC,kBAAkB,EAAE,sBAAsB;IAC1C,KAAK,EAAE,YAAY;IACnB,eAAe,EAAE,yBAAyB;IAC1C,OAAO,EAAE,eAAe;IACxB,gBAAgB,EAAE,4BAA4B;IAC9C,qBAAqB,EAAE,oCAAoC;IAC3D,UAAU,EAAE,mBAAmB;IAC/B,cAAc,EAAE,uBAAuB;IACvC,oBAAoB,EAAE,4BAA4B;IAClD,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,UAAU;IACjB,oBAAoB,EAAE,wBAAwB;IAC9C,eAAe,EAAE,mBAAmB;IACpC,sBAAsB,EAAE,gCAAgC;IACxD,eAAe,EAAE,2BAA2B;IAC5C,UAAU,EAAE,kBAAkB;IAC9B,OAAO,EAAE,iBAAiB;IAC1B,iBAAiB,EAAE,sBAAsB;IACzC,YAAY,EAAE,oBAAoB;IAClC,iBAAiB,EAAE,yBAAyB;IAC5C,gBAAgB,EAAE,wBAAwB;IAC1C,iBAAiB,EAAE,yBAAyB;IAC5C,kBAAkB,EAAE,0BAA0B;IAC9C,mBAAmB,EAAE,2BAA2B;IAChD,YAAY,EAAE,uBAAuB;CACtC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IACvC,IAAI;IACJ,OAAO;IACP,KAAK;IACL,UAAU;IACV,OAAO;IACP,SAAS;IACT,SAAS;IACT,UAAU;IACV,KAAK;IACL,SAAS;IACT,WAAW;IACX,YAAY;CACb,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA2B;IACnE,iBAAiB,EAAE,2BAA2B;IAC9C,gBAAgB,EAAE,0BAA0B;IAC5C,qBAAqB,EAAE,wCAAwC;IAC/D,kBAAkB,EAAE,0CAA0C;IAC9D,mBAAmB,EAAE,4CAA4C;CAClE,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IAC/C,mBAAmB;IACnB,kBAAkB;CACnB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,uEAAuE;IACvE,OAAO;IACP,OAAO;IACP,YAAY;IACZ,UAAU;IACV,SAAS;IACT,eAAe;IACf,eAAe;IACf,cAAc;IACd,iBAAiB;IACjB,8BAA8B;IAC9B,YAAY;IACZ,iBAAiB;IACjB,WAAW;IACX,iBAAiB;IACjB,cAAc;IACd,oBAAoB;IACpB,uBAAuB;IACvB,oBAAoB;IACpB,kBAAkB;IAClB,cAAc;IACd,mBAAmB;IACnB,wBAAwB;IACxB,eAAe;IACf,oBAAoB;IACpB,aAAa;IACb,4BAA4B;IAC5B,iBAAiB;IACjB,mBAAmB;IACnB,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,oBAAoB;IACpB,kCAAkC;IAClC,iBAAiB;IACjB,kBAAkB;IAClB,oBAAoB;IACpB,iBAAiB;IACjB,SAAS;IACT,kBAAkB;IAClB,uBAAuB;IACvB,YAAY;IACZ,gBAAgB;IAChB,sBAAsB;IACtB,sBAAsB;IACtB,iBAAiB;IACjB,wBAAwB;IACxB,iBAAiB;IACjB,YAAY;IACZ,mBAAmB;IACnB,cAAc;IACd,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,oBAAoB;IACpB,qBAAqB;IACrB,cAAc;IACd,2EAA2E;IAC3E,mBAAmB;IACnB,kBAAkB;IAClB,uBAAuB;IACvB,oBAAoB;IACpB,qBAAqB;CACtB,CAAC"}

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SettingsMigration } from '../types.js';
+/**
+ * Heuristic indicators for deciding whether an object is "V1-like".
+ *
+ * Detection strategy:
+ * - A file is considered migratable as V1 when:
+ *   1) It is not explicitly versioned as V2+ (`$version` is missing or invalid), and
+ *   2) At least one indicator key appears in a legacy-compatible top-level shape.
+ * - Indicator list intentionally excludes keys that are valid top-level entries in
+ *   both old and new structures to reduce false positives.
+ *
+ * Shape rule:
+ * - Object values for indicator keys are treated as already-nested V2-like content
+ *   and do not alone trigger migration.
+ * - Primitive/array/null values on indicator keys are treated as legacy V1 signals.
+ */
+/**
+ * V1 -> V2 migration (structural normalization stage).
+ *
+ * Migration contract:
+ * - Input: settings in legacy V1-like shape (mostly flat, may contain mixed partial V2).
+ * - Output: V2-compatible nested structure with `$version: 2`.
+ * - No semantic inversion of disable* naming in this stage.
+ *
+ * Data-preservation strategy:
+ * - Prefer transforming known keys into canonical V2 locations.
+ * - Preserve unrecognized keys verbatim.
+ * - Preserve parent-path scalar values when nested writes would collide with them.
+ * - Preserve/merge existing partial V2 objects where safe.
+ *
+ * This class intentionally optimizes for backward compatibility and non-destructive
+ * behavior over aggressive normalization.
+ */
+export declare class V1ToV2Migration implements SettingsMigration {
+    readonly fromVersion = 1;
+    readonly toVersion = 2;
+    /**
+     * Determines whether this migration should execute.
+     *
+     * Decision strategy:
+     * - Hard-stop when `$version` is a number >= 2 (already V2+).
+     * - Otherwise, scan indicator keys and trigger only when at least one indicator is
+     *   still in legacy top-level shape (primitive/array/null).
+     *
+     * Mixed-shape tolerance:
+     * - Files that are partially migrated are supported; V2-like object-valued indicators
+     *   are ignored while legacy-shaped indicators can still trigger migration.
+     */
+    shouldMigrate(settings: unknown): boolean;
+    /**
+     * Performs non-destructive V1 -> V2 transformation.
+     *
+     * Detailed strategy:
+     * 1) Relocate known V1 keys using `V1_TO_V2_MIGRATION_MAP`.
+     *    - If a source value is already an object and maps to a child path of itself
+     *      (partial V2 shape), merge child properties into target path.
+     * 2) Relocate disable* keys into V2 disable* locations.
+     *    - Consolidated keys (`disableAutoUpdate`, `disableUpdateNag`): normalize to
+     *      boolean with stable-compatible presence semantics (`value === true`).
+     *    - Other disable* keys: migrate only boolean values.
+     * 3) Preserve `mcpServers` top-level placement.
+     * 4) Carry over remaining keys:
+     *    - If a key is parent of migrated nested paths, merge unprocessed object children.
+     *    - If parent value is non-object, preserve that scalar/array/null as-is.
+     *    - Otherwise copy untouched key/value.
+     * 5) Stamp `$version = 2`.
+     *
+     * The method is pure with respect to input mutation.
+     */
+    migrate(settings: unknown, _scope: string): {
+        settings: unknown;
+        warnings: string[];
+    };
+}
+/** Singleton instance of V1→V2 migration */
+export declare const v1ToV2Migration: V1ToV2Migration;

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2.js

@@ -0,0 +1,222 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CONSOLIDATED_DISABLE_KEYS, V1_INDICATOR_KEYS, V1_TO_V2_MIGRATION_MAP, V1_TO_V2_PRESERVE_DISABLE_MAP, V2_CONTAINER_KEYS, } from './v1-to-v2-shared.js';
+import { setNestedPropertySafe } from '../../../utils/settingsUtils.js';
+/**
+ * Heuristic indicators for deciding whether an object is "V1-like".
+ *
+ * Detection strategy:
+ * - A file is considered migratable as V1 when:
+ *   1) It is not explicitly versioned as V2+ (`$version` is missing or invalid), and
+ *   2) At least one indicator key appears in a legacy-compatible top-level shape.
+ * - Indicator list intentionally excludes keys that are valid top-level entries in
+ *   both old and new structures to reduce false positives.
+ *
+ * Shape rule:
+ * - Object values for indicator keys are treated as already-nested V2-like content
+ *   and do not alone trigger migration.
+ * - Primitive/array/null values on indicator keys are treated as legacy V1 signals.
+ */
+/**
+ * V1 -> V2 migration (structural normalization stage).
+ *
+ * Migration contract:
+ * - Input: settings in legacy V1-like shape (mostly flat, may contain mixed partial V2).
+ * - Output: V2-compatible nested structure with `$version: 2`.
+ * - No semantic inversion of disable* naming in this stage.
+ *
+ * Data-preservation strategy:
+ * - Prefer transforming known keys into canonical V2 locations.
+ * - Preserve unrecognized keys verbatim.
+ * - Preserve parent-path scalar values when nested writes would collide with them.
+ * - Preserve/merge existing partial V2 objects where safe.
+ *
+ * This class intentionally optimizes for backward compatibility and non-destructive
+ * behavior over aggressive normalization.
+ */
+export class V1ToV2Migration {
+    fromVersion = 1;
+    toVersion = 2;
+    /**
+     * Determines whether this migration should execute.
+     *
+     * Decision strategy:
+     * - Hard-stop when `$version` is a number >= 2 (already V2+).
+     * - Otherwise, scan indicator keys and trigger only when at least one indicator is
+     *   still in legacy top-level shape (primitive/array/null).
+     *
+     * Mixed-shape tolerance:
+     * - Files that are partially migrated are supported; V2-like object-valued indicators
+     *   are ignored while legacy-shaped indicators can still trigger migration.
+     */
+    shouldMigrate(settings) {
+        if (typeof settings !== 'object' || settings === null) {
+            return false;
+        }
+        const s = settings;
+        // If $version exists and is a number >= 2, it's not V1
+        const version = s['$version'];
+        if (typeof version === 'number' && version >= 2) {
+            return false;
+        }
+        // Check for V1 indicator keys with primitive values
+        // A setting is considered V1 if ANY indicator key has a primitive value
+        // (string, number, boolean, null, or array) at the top level.
+        // Keys with object values are skipped as they may already be in V2 format.
+        return V1_INDICATOR_KEYS.some((key) => {
+            if (!(key in s)) {
+                return false;
+            }
+            const value = s[key];
+            // Skip keys with object values - they may already be in V2 nested format
+            // But don't let them block migration of other keys
+            if (typeof value === 'object' &&
+                value !== null &&
+                !Array.isArray(value)) {
+                // This key appears to be in V2 format, skip it but continue
+                // checking other keys
+                return false;
+            }
+            // Found a key with primitive value - this is V1 format
+            return true;
+        });
+    }
+    /**
+     * Performs non-destructive V1 -> V2 transformation.
+     *
+     * Detailed strategy:
+     * 1) Relocate known V1 keys using `V1_TO_V2_MIGRATION_MAP`.
+     *    - If a source value is already an object and maps to a child path of itself
+     *      (partial V2 shape), merge child properties into target path.
+     * 2) Relocate disable* keys into V2 disable* locations.
+     *    - Consolidated keys (`disableAutoUpdate`, `disableUpdateNag`): normalize to
+     *      boolean with stable-compatible presence semantics (`value === true`).
+     *    - Other disable* keys: migrate only boolean values.
+     * 3) Preserve `mcpServers` top-level placement.
+     * 4) Carry over remaining keys:
+     *    - If a key is parent of migrated nested paths, merge unprocessed object children.
+     *    - If parent value is non-object, preserve that scalar/array/null as-is.
+     *    - Otherwise copy untouched key/value.
+     * 5) Stamp `$version = 2`.
+     *
+     * The method is pure with respect to input mutation.
+     */
+    migrate(settings, _scope) {
+        if (typeof settings !== 'object' || settings === null) {
+            throw new Error('Settings must be an object');
+        }
+        const source = settings;
+        const result = {};
+        const processedKeys = new Set();
+        const warnings = [];
+        // Step 1: Map known V1 keys to V2 nested paths
+        for (const [v1Key, v2Path] of Object.entries(V1_TO_V2_MIGRATION_MAP)) {
+            if (v1Key in source) {
+                const value = source[v1Key];
+                // Safety check: If this key is a V2 container (like 'model') and it's
+                // already an object, it's likely already in V2 format. Skip migration
+                // to prevent double-nesting (e.g., model.name.name).
+                if (V2_CONTAINER_KEYS.has(v1Key) &&
+                    typeof value === 'object' &&
+                    value !== null &&
+                    !Array.isArray(value)) {
+                    // This is already a V2 container, carry it over as-is
+                    result[v1Key] = value;
+                    processedKeys.add(v1Key);
+                    continue;
+                }
+                // If value is already an object and the path matches the key,
+                // it might be a partial V2 structure. Merge its contents.
+                if (typeof value === 'object' &&
+                    value !== null &&
+                    !Array.isArray(value) &&
+                    v2Path.startsWith(v1Key + '.')) {
+                    // Merge nested properties from this partial V2 structure
+                    for (const [nestedKey, nestedValue] of Object.entries(value)) {
+                        setNestedPropertySafe(result, `${v2Path}.${nestedKey}`, nestedValue);
+                    }
+                }
+                else {
+                    setNestedPropertySafe(result, v2Path, value);
+                }
+                processedKeys.add(v1Key);
+            }
+        }
+        // Step 2: Map V1 disable* keys to V2 nested disable* paths
+        for (const [v1Key, v2Path] of Object.entries(V1_TO_V2_PRESERVE_DISABLE_MAP)) {
+            if (v1Key in source) {
+                const value = source[v1Key];
+                if (CONSOLIDATED_DISABLE_KEYS.has(v1Key)) {
+                    // Preserve stable behavior: consolidated keys use presence semantics.
+                    // Only literal true remains true; all other present values become false.
+                    setNestedPropertySafe(result, v2Path, value === true);
+                }
+                else if (typeof value === 'boolean') {
+                    // Non-consolidated disable* keys only migrate when explicitly boolean.
+                    setNestedPropertySafe(result, v2Path, value);
+                }
+                processedKeys.add(v1Key);
+            }
+        }
+        // Step 3: Preserve mcpServers at the top level
+        if ('mcpServers' in source) {
+            result['mcpServers'] = source['mcpServers'];
+            processedKeys.add('mcpServers');
+        }
+        // Step 4: Carry over any unrecognized keys (including unknown nested objects)
+        // Important: Skip keys that are parent paths of already-migrated properties
+        // to avoid overwriting merged structures (e.g., 'ui' should not overwrite 'ui.theme')
+        for (const key of Object.keys(source)) {
+            if (!processedKeys.has(key)) {
+                // Check if this key is a parent of any already-migrated path
+                const isParentOfMigratedPath = Array.from(processedKeys).some((processedKey) => {
+                    // Get the v2 path for this processed key
+                    const v2Path = V1_TO_V2_MIGRATION_MAP[processedKey] ||
+                        V1_TO_V2_PRESERVE_DISABLE_MAP[processedKey];
+                    if (!v2Path)
+                        return false;
+                    // Check if the v2 path starts with this key + '.'
+                    return v2Path.startsWith(key + '.');
+                });
+                if (isParentOfMigratedPath) {
+                    // This key is a parent of an already-migrated path
+                    // Merge its unprocessed children instead of overwriting
+                    const existingValue = source[key];
+                    if (typeof existingValue === 'object' &&
+                        existingValue !== null &&
+                        !Array.isArray(existingValue)) {
+                        for (const [nestedKey, nestedValue] of Object.entries(existingValue)) {
+                            // Only merge if this nested key wasn't already processed
+                            const fullNestedPath = `${key}.${nestedKey}`;
+                            const wasProcessed = Array.from(processedKeys).some((processedKey) => {
+                                const v2Path = V1_TO_V2_MIGRATION_MAP[processedKey] ||
+                                    V1_TO_V2_PRESERVE_DISABLE_MAP[processedKey];
+                                return v2Path === fullNestedPath;
+                            });
+                            if (!wasProcessed) {
+                                setNestedPropertySafe(result, fullNestedPath, nestedValue);
+                            }
+                        }
+                    }
+                    else {
+                        // Preserve non-object parent values to match legacy overwrite semantics.
+                        result[key] = source[key];
+                    }
+                }
+                else {
+                    // Not a parent path, safe to copy as-is
+                    result[key] = source[key];
+                }
+            }
+        }
+        // Step 5: Set version to 2
+        result['$version'] = 2;
+        return { settings: result, warnings };
+    }
+}
+/** Singleton instance of V1→V2 migration */
+export const v1ToV2Migration = new V1ToV2Migration();
+//# sourceMappingURL=v1-to-v2.js.map

package/dist/CLI/packages/cli/src/config/migration/versions/v1-to-v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1-to-v2.js","sourceRoot":"","sources":["../../../../../../../../src/config/migration/versions/v1-to-v2.ts"],"names":[],"mappings":"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"}

package/dist/CLI/packages/cli/src/config/migration/versions/v2-to-v3.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SettingsMigration } from '../types.js';
+/**
+ * V2 -> V3 migration (boolean polarity normalization stage).
+ *
+ * Migration contract:
+ * - Input: V2 settings object (`$version: 2`).
+ * - Output: `$version: 3` with deprecated disable* fields removed and
+ *   valid values migrated to enable* equivalents.
+ *
+ * Compatibility strategy:
+ * - Accept boolean values and coercible strings "true"/"false".
+ * - Remove invalid deprecated values (rather than preserving them).
+ * - Emit warnings for each removed invalid deprecated key.
+ * - Always bump version to 3 so future loads are idempotent and skip repeated checks.
+ */
+export declare class V2ToV3Migration implements SettingsMigration {
+    readonly fromVersion = 2;
+    readonly toVersion = 3;
+    /**
+     * Migration trigger rule.
+     *
+     * Execute only when `$version === 2`.
+     * This includes V2 files with no migratable disable* booleans so that version
+     * metadata still advances to 3.
+     */
+    shouldMigrate(settings: unknown): boolean;
+    /**
+     * Applies V2 -> V3 transformation with deterministic deprecated-key cleanup.
+     *
+     * Detailed strategy:
+     * 1) Clone input.
+     * 2) Process consolidated paths first:
+     *    - Inspect each source path.
+     *    - Normalize each present value (boolean / coercible string / invalid).
+     *    - Always delete present deprecated source key.
+     *    - Valid normalized values contribute to aggregate.
+     *    - Invalid values emit warnings.
+     *    - Emit consolidated target when at least one valid source was consumed.
+     * 3) Process remaining one-to-one mappings:
+     *    - For each unmapped source, normalize value.
+     *    - If valid -> delete old key and write inverted target.
+     *    - If invalid -> delete old key and emit warning.
+     * 4) Set `$version = 3`.
+     *
+     * Guarantees:
+     * - Input object is not mutated.
+     * - Valid migration and invalid cleanup are deterministic.
+     * - Deprecated disable* keys are not retained after migration.
+     */
+    migrate(settings: unknown, scope: string): {
+        settings: unknown;
+        warnings: string[];
+    };
+}
+/** Singleton instance of V2→V3 migration */
+export declare const v2ToV3Migration: V2ToV3Migration;