Merge branch 'main' into feat/browser-allowed-domain

packages/cli/src/config/extension-manager.test.ts

@@ -345,4 +345,144 @@ describe('ExtensionManager', () => {
       }
     });
   });
+
+  describe('Extension Renaming', () => {
+    it('should support renaming an extension during update', async () => {
+      // 1. Setup existing extension
+      const oldName = 'old-name';
+      const newName = 'new-name';
+      const extDir = path.join(userExtensionsDir, oldName);
+      fs.mkdirSync(extDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(extDir, 'gemini-extension.json'),
+        JSON.stringify({ name: oldName, version: '1.0.0' }),
+      );
+      fs.writeFileSync(
+        path.join(extDir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: extDir }),
+      );
+
+      await extensionManager.loadExtensions();
+
+      // 2. Create a temporary "new" version with a different name
+      const newSourceDir = fs.mkdtempSync(
+        path.join(tempHomeDir, 'new-source-'),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'gemini-extension.json'),
+        JSON.stringify({ name: newName, version: '1.1.0' }),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: newSourceDir }),
+      );
+
+      // 3. Update the extension
+      await extensionManager.installOrUpdateExtension(
+        { type: 'local', source: newSourceDir },
+        { name: oldName, version: '1.0.0' },
+      );
+
+      // 4. Verify old directory is gone and new one exists
+      expect(fs.existsSync(path.join(userExtensionsDir, oldName))).toBe(false);
+      expect(fs.existsSync(path.join(userExtensionsDir, newName))).toBe(true);
+
+      // Verify the loaded state is updated
+      const extensions = extensionManager.getExtensions();
+      expect(extensions.some((e) => e.name === newName)).toBe(true);
+      expect(extensions.some((e) => e.name === oldName)).toBe(false);
+    });
+
+    it('should carry over enablement status when renaming', async () => {
+      const oldName = 'old-name';
+      const newName = 'new-name';
+      const extDir = path.join(userExtensionsDir, oldName);
+      fs.mkdirSync(extDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(extDir, 'gemini-extension.json'),
+        JSON.stringify({ name: oldName, version: '1.0.0' }),
+      );
+      fs.writeFileSync(
+        path.join(extDir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: extDir }),
+      );
+
+      // Enable it
+      const enablementManager = extensionManager.getEnablementManager();
+      enablementManager.enable(oldName, true, tempHomeDir);
+
+      await extensionManager.loadExtensions();
+      const extension = extensionManager.getExtensions()[0];
+      expect(extension.isActive).toBe(true);
+
+      const newSourceDir = fs.mkdtempSync(
+        path.join(tempHomeDir, 'new-source-'),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'gemini-extension.json'),
+        JSON.stringify({ name: newName, version: '1.1.0' }),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: newSourceDir }),
+      );
+
+      await extensionManager.installOrUpdateExtension(
+        { type: 'local', source: newSourceDir },
+        { name: oldName, version: '1.0.0' },
+      );
+
+      // Verify new name is enabled
+      expect(enablementManager.isEnabled(newName, tempHomeDir)).toBe(true);
+      // Verify old name is removed from enablement
+      expect(enablementManager.readConfig()[oldName]).toBeUndefined();
+    });
+
+    it('should prevent renaming if the new name conflicts with an existing extension', async () => {
+      // Setup two extensions
+      const ext1Dir = path.join(userExtensionsDir, 'ext1');
+      fs.mkdirSync(ext1Dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(ext1Dir, 'gemini-extension.json'),
+        JSON.stringify({ name: 'ext1', version: '1.0.0' }),
+      );
+      fs.writeFileSync(
+        path.join(ext1Dir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: ext1Dir }),
+      );
+
+      const ext2Dir = path.join(userExtensionsDir, 'ext2');
+      fs.mkdirSync(ext2Dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(ext2Dir, 'gemini-extension.json'),
+        JSON.stringify({ name: 'ext2', version: '1.0.0' }),
+      );
+      fs.writeFileSync(
+        path.join(ext2Dir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: ext2Dir }),
+      );
+
+      await extensionManager.loadExtensions();
+
+      // Try to update ext1 to name 'ext2'
+      const newSourceDir = fs.mkdtempSync(
+        path.join(tempHomeDir, 'new-source-'),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'gemini-extension.json'),
+        JSON.stringify({ name: 'ext2', version: '1.1.0' }),
+      );
+      fs.writeFileSync(
+        path.join(newSourceDir, 'metadata.json'),
+        JSON.stringify({ type: 'local', source: newSourceDir }),
+      );
+
+      await expect(
+        extensionManager.installOrUpdateExtension(
+          { type: 'local', source: newSourceDir },
+          { name: 'ext1', version: '1.0.0' },
+        ),
+      ).rejects.toThrow(/already installed/);
+    });
+  });
 });

packages/cli/src/config/extension-manager.ts

@@ -129,6 +129,10 @@ export class ExtensionManager extends ExtensionLoader {
     this.requestSetting = options.requestSetting ?? undefined;
   }
 
+  getEnablementManager(): ExtensionEnablementManager {
+    return this.extensionEnablementManager;
+  }
+
   setRequestConsent(
     requestConsent: (consent: string) => Promise<boolean>,
   ): void {
@@ -271,17 +275,28 @@ Would you like to attempt to install via "git clone" instead?`,
         newExtensionConfig = await this.loadExtensionConfig(localSourcePath);
 
         const newExtensionName = newExtensionConfig.name;
+        const previousName = previousExtensionConfig?.name ?? newExtensionName;
         const previous = this.getExtensions().find(
-          (installed) => installed.name === newExtensionName,
+          (installed) => installed.name === previousName,
         );
+        const nameConflict = this.getExtensions().find(
+          (installed) =>
+            installed.name === newExtensionName &&
+            installed.name !== previousName,
+        );
+
         if (isUpdate && !previous) {
           throw new Error(
-            `Extension "${newExtensionName}" was not already installed, cannot update it.`,
+            `Extension "${previousName}" was not already installed, cannot update it.`,
           );
         } else if (!isUpdate && previous) {
           throw new Error(
             `Extension "${newExtensionName}" is already installed. Please uninstall it first.`,
           );
+        } else if (isUpdate && nameConflict) {
+          throw new Error(
+            `Cannot update to "${newExtensionName}" because an extension with that name is already installed.`,
+          );
         }
 
         const newHasHooks = fs.existsSync(
@@ -298,6 +313,11 @@ Would you like to attempt to install via "git clone" instead?`,
           path.join(localSourcePath, 'skills'),
         );
         const previousSkills = previous?.skills ?? [];
+        const isMigrating = Boolean(
+          previous &&
+            previous.installMetadata &&
+            previous.installMetadata.source !== installMetadata.source,
+        );
 
         await maybeRequestConsentOrFail(
           newExtensionConfig,
@@ -307,19 +327,46 @@ Would you like to attempt to install via "git clone" instead?`,
           previousHasHooks,
           newSkills,
           previousSkills,
+          isMigrating,
         );
         const extensionId = getExtensionId(newExtensionConfig, installMetadata);
         const destinationPath = new ExtensionStorage(
           newExtensionName,
         ).getExtensionDir();
+
+        if (
+          (!isUpdate || newExtensionName !== previousName) &&
+          fs.existsSync(destinationPath)
+        ) {
+          throw new Error(
+            `Cannot install extension "${newExtensionName}" because a directory with that name already exists. Please remove it manually.`,
+          );
+        }
+
         let previousSettings: Record<string, string> | undefined;
-        if (isUpdate) {
+        let wasEnabledGlobally = false;
+        let wasEnabledWorkspace = false;
+        if (isUpdate && previousExtensionConfig) {
+          const previousExtensionId = previous?.installMetadata
+            ? getExtensionId(previousExtensionConfig, previous.installMetadata)
+            : extensionId;
           previousSettings = await getEnvContents(
             previousExtensionConfig,
-            extensionId,
+            previousExtensionId,
             this.workspaceDir,
           );
-          await this.uninstallExtension(newExtensionName, isUpdate);
+          if (newExtensionName !== previousName) {
+            wasEnabledGlobally = this.extensionEnablementManager.isEnabled(
+              previousName,
+              homedir(),
+            );
+            wasEnabledWorkspace = this.extensionEnablementManager.isEnabled(
+              previousName,
+              this.workspaceDir,
+            );
+            this.extensionEnablementManager.remove(previousName);
+          }
+          await this.uninstallExtension(previousName, isUpdate);
         }
 
         await fs.promises.mkdir(destinationPath, { recursive: true });
@@ -392,6 +439,18 @@ Would you like to attempt to install via "git clone" instead?`,
               CoreToolCallStatus.Success,
             ),
           );
+
+          if (newExtensionName !== previousName) {
+            if (wasEnabledGlobally) {
+              await this.enableExtension(newExtensionName, SettingScope.User);
+            }
+            if (wasEnabledWorkspace) {
+              await this.enableExtension(
+                newExtensionName,
+                SettingScope.Workspace,
+              );
+            }
+          }
         } else {
           await logExtensionInstallEvent(
             this.telemetryConfig,
@@ -873,6 +932,7 @@ Would you like to attempt to install via "git clone" instead?`,
         path: effectiveExtensionPath,
         contextFiles,
         installMetadata,
+        migratedTo: config.migratedTo,
         mcpServers: config.mcpServers,
         excludeTools: config.excludeTools,
         hooks,

packages/cli/src/config/extension.ts

@@ -42,6 +42,10 @@ export interface ExtensionConfig {
      */
     directory?: string;
   };
+  /**
+   * Used to migrate an extension to a new repository source.
+   */
+  migratedTo?: string;
 }
 
 export interface ExtensionUpdateInfo {

packages/cli/src/config/extensions/__snapshots__/consent-consent-maybeRequestConsentOrFail-consent-string-generation-should-request-consent-if-extension-is-migrated.snap.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="122" viewBox="0 0 920 122">
+  <style>
+    text { font-family: Consolas, "Courier New", monospace; font-size: 14px; dominant-baseline: text-before-edge; white-space: pre; }
+  </style>
+  <rect width="920" height="122" fill="#000000" />
+  <g transform="translate(10, 10)">
+    <text x="0" y="2" fill="#ffffff" textLength="900" lengthAdjust="spacingAndGlyphs">Migrating extension &quot;old-ext&quot; to a new repository, renaming to &quot;test-ext&quot;, and installing updates.  </text>
+    <text x="0" y="36" fill="#cdcd00" textLength="891" lengthAdjust="spacingAndGlyphs">The extension you are about to install may have been created by a third-party developer and sourced</text>
+    <text x="0" y="53" fill="#cdcd00" textLength="882" lengthAdjust="spacingAndGlyphs">from a public repository. Google does not vet, endorse, or guarantee the functionality or security</text>
+    <text x="0" y="70" fill="#cdcd00" textLength="846" lengthAdjust="spacingAndGlyphs">of extensions. Please carefully inspect any extension and its source code before installing to</text>
+    <text x="0" y="87" fill="#cdcd00" textLength="630" lengthAdjust="spacingAndGlyphs">understand the permissions it requires and the actions it may perform.</text>
+  </g>
+</svg>

packages/cli/src/config/extensions/__snapshots__/consent.test.ts.snap

@@ -24,6 +24,15 @@ of extensions. Please carefully inspect any extension and its source code before
 understand the permissions it requires and the actions it may perform."
 `;
 
+exports[`consent > maybeRequestConsentOrFail > consent string generation > should request consent if extension is migrated 1`] = `
+"Migrating extension "old-ext" to a new repository, renaming to "test-ext", and installing updates.
+
+The extension you are about to install may have been created by a third-party developer and sourced
+from a public repository. Google does not vet, endorse, or guarantee the functionality or security
+of extensions. Please carefully inspect any extension and its source code before installing to
+understand the permissions it requires and the actions it may perform."
+`;
+
 exports[`consent > maybeRequestConsentOrFail > consent string generation > should request consent if skills change 1`] = `
 "Installing extension "test-ext".
 This extension will run the following MCP servers:

packages/cli/src/config/extensions/consent.test.ts

@@ -287,6 +287,25 @@ describe('consent', () => {
         expect(requestConsent).toHaveBeenCalledTimes(1);
       });
 
+      it('should request consent if extension is migrated', async () => {
+        const requestConsent = vi.fn().mockResolvedValue(true);
+        await maybeRequestConsentOrFail(
+          baseConfig,
+          requestConsent,
+          false,
+          { ...baseConfig, name: 'old-ext' },
+          false,
+          [],
+          [],
+          true,
+        );
+
+        expect(requestConsent).toHaveBeenCalledTimes(1);
+        let consentString = requestConsent.mock.calls[0][0] as string;
+        consentString = normalizePathsForSnapshot(consentString, tempDir);
+        await expectConsentSnapshot(consentString);
+      });
+
       it('should request consent if skills change', async () => {
         const skill1Dir = path.join(tempDir, 'skill1');
         const skill2Dir = path.join(tempDir, 'skill2');

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

@@ -148,11 +148,30 @@ async function extensionConsentString(
   extensionConfig: ExtensionConfig,
   hasHooks: boolean,
   skills: SkillDefinition[] = [],
+  previousName?: string,
+  wasMigrated?: boolean,
 ): Promise<string> {
   const sanitizedConfig = escapeAnsiCtrlCodes(extensionConfig);
   const output: string[] = [];
   const mcpServerEntries = Object.entries(sanitizedConfig.mcpServers || {});
-  output.push(`Installing extension "${sanitizedConfig.name}".`);
+
+  if (wasMigrated) {
+    if (previousName && previousName !== sanitizedConfig.name) {
+      output.push(
+        `Migrating extension "${previousName}" to a new repository, renaming to "${sanitizedConfig.name}", and installing updates.`,
+      );
+    } else {
+      output.push(
+        `Migrating extension "${sanitizedConfig.name}" to a new repository and installing updates.`,
+      );
+    }
+  } else if (previousName && previousName !== sanitizedConfig.name) {
+    output.push(
+      `Renaming extension "${previousName}" to "${sanitizedConfig.name}" and installing updates.`,
+    );
+  } else {
+    output.push(`Installing extension "${sanitizedConfig.name}".`);
+  }
 
   if (mcpServerEntries.length) {
     output.push('This extension will run the following MCP servers:');
@@ -231,11 +250,14 @@ export async function maybeRequestConsentOrFail(
   previousHasHooks?: boolean,
   skills: SkillDefinition[] = [],
   previousSkills: SkillDefinition[] = [],
+  isMigrating: boolean = false,
 ) {
   const extensionConsent = await extensionConsentString(
     extensionConfig,
     hasHooks,
     skills,
+    previousExtensionConfig?.name,
+    isMigrating,
   );
   if (previousExtensionConfig) {
     const previousExtensionConsent = await extensionConsentString(

packages/cli/src/config/extensions/github.test.ts

@@ -285,6 +285,23 @@ describe('github.ts', () => {
         ExtensionUpdateState.NOT_UPDATABLE,
       );
     });
+
+    it('should check migratedTo source if present and return UPDATE_AVAILABLE', async () => {
+      mockGit.getRemotes.mockResolvedValue([
+        { name: 'origin', refs: { fetch: 'new-url' } },
+      ]);
+      mockGit.listRemote.mockResolvedValue('hash\tHEAD');
+      mockGit.revparse.mockResolvedValue('hash');
+
+      const ext = {
+        path: '/path',
+        migratedTo: 'new-url',
+        installMetadata: { type: 'git', source: 'old-url' },
+      } as unknown as GeminiCLIExtension;
+      expect(await checkForExtensionUpdate(ext, mockExtensionManager)).toBe(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+    });
   });
 
   describe('downloadFromGitHubRelease', () => {

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

@@ -203,6 +203,24 @@ export async function checkForExtensionUpdate(
   ) {
     return ExtensionUpdateState.NOT_UPDATABLE;
   }
+
+  if (extension.migratedTo) {
+    const migratedState = await checkForExtensionUpdate(
+      {
+        ...extension,
+        installMetadata: { ...installMetadata, source: extension.migratedTo },
+        migratedTo: undefined,
+      },
+      extensionManager,
+    );
+    if (
+      migratedState === ExtensionUpdateState.UPDATE_AVAILABLE ||
+      migratedState === ExtensionUpdateState.UP_TO_DATE
+    ) {
+      return ExtensionUpdateState.UPDATE_AVAILABLE;
+    }
+  }
+
   try {
     if (installMetadata.type === 'git') {
       const git = simpleGit(extension.path);

packages/cli/src/config/extensions/update.test.ts

@@ -184,6 +184,54 @@ describe('Extension Update Logic', () => {
       });
     });
 
+    it('should migrate source if migratedTo is set and an update is available', async () => {
+      vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
+        Promise.resolve({
+          name: 'test-extension',
+          version: '1.0.0',
+        }),
+      );
+      vi.mocked(
+        mockExtensionManager.installOrUpdateExtension,
+      ).mockResolvedValue({
+        ...mockExtension,
+        version: '1.1.0',
+      });
+      vi.mocked(checkForExtensionUpdate).mockResolvedValue(
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+      );
+
+      const extensionWithMigratedTo = {
+        ...mockExtension,
+        migratedTo: 'https://new-source.com/repo.git',
+      };
+
+      await updateExtension(
+        extensionWithMigratedTo,
+        mockExtensionManager,
+        ExtensionUpdateState.UPDATE_AVAILABLE,
+        mockDispatch,
+      );
+
+      expect(checkForExtensionUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          installMetadata: expect.objectContaining({
+            source: 'https://new-source.com/repo.git',
+          }),
+        }),
+        mockExtensionManager,
+      );
+
+      expect(
+        mockExtensionManager.installOrUpdateExtension,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          source: 'https://new-source.com/repo.git',
+        }),
+        expect.anything(),
+      );
+    });
+
     it('should set state to UPDATED if enableExtensionReloading is true', async () => {
       vi.mocked(mockExtensionManager.loadExtensionConfig).mockReturnValue(
         Promise.resolve({

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

@@ -55,6 +55,24 @@ export async function updateExtension(
     });
     throw new Error(`Extension is linked so does not need to be updated`);
   }
+
+  if (extension.migratedTo) {
+    const migratedState = await checkForExtensionUpdate(
+      {
+        ...extension,
+        installMetadata: { ...installMetadata, source: extension.migratedTo },
+        migratedTo: undefined,
+      },
+      extensionManager,
+    );
+    if (
+      migratedState === ExtensionUpdateState.UPDATE_AVAILABLE ||
+      migratedState === ExtensionUpdateState.UP_TO_DATE
+    ) {
+      installMetadata.source = extension.migratedTo;
+    }
+  }
+
   const originalVersion = extension.version;
 
   const tempDir = await ExtensionStorage.createTmpDir();

packages/cli/src/config/keyBindings.test.ts

@@ -1,93 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect } from 'vitest';
-import type { KeyBindingConfig } from './keyBindings.js';
-import {
-  Command,
-  commandCategories,
-  commandDescriptions,
-  defaultKeyBindings,
-} from './keyBindings.js';
-
-describe('keyBindings config', () => {
-  describe('defaultKeyBindings', () => {
-    it('should have bindings for all commands', () => {
-      const commands = Object.values(Command);
-
-      for (const command of commands) {
-        expect(defaultKeyBindings[command]).toBeDefined();
-        expect(Array.isArray(defaultKeyBindings[command])).toBe(true);
-        expect(defaultKeyBindings[command]?.length).toBeGreaterThan(0);
-      }
-    });
-
-    it('should have valid key binding structures', () => {
-      for (const [_, bindings] of Object.entries(defaultKeyBindings)) {
-        for (const binding of bindings) {
-          // Each binding must have a key name
-          expect(typeof binding.key).toBe('string');
-          expect(binding.key.length).toBeGreaterThan(0);
-
-          // Modifier properties should be boolean or undefined
-          if (binding.shift !== undefined) {
-            expect(typeof binding.shift).toBe('boolean');
-          }
-          if (binding.alt !== undefined) {
-            expect(typeof binding.alt).toBe('boolean');
-          }
-          if (binding.ctrl !== undefined) {
-            expect(typeof binding.ctrl).toBe('boolean');
-          }
-          if (binding.cmd !== undefined) {
-            expect(typeof binding.cmd).toBe('boolean');
-          }
-        }
-      }
-    });
-
-    it('should export all required types', () => {
-      // Basic type checks
-      expect(typeof Command.HOME).toBe('string');
-      expect(typeof Command.END).toBe('string');
-
-      // Config should be readonly
-      const config: KeyBindingConfig = defaultKeyBindings;
-      expect(config[Command.HOME]).toBeDefined();
-    });
-  });
-
-  describe('command metadata', () => {
-    const commandValues = Object.values(Command);
-
-    it('has a description entry for every command', () => {
-      const describedCommands = Object.keys(commandDescriptions);
-      expect(describedCommands.sort()).toEqual([...commandValues].sort());
-
-      for (const command of commandValues) {
-        expect(typeof commandDescriptions[command]).toBe('string');
-        expect(commandDescriptions[command]?.trim()).not.toHaveLength(0);
-      }
-    });
-
-    it('categorizes each command exactly once', () => {
-      const seen = new Set<Command>();
-
-      for (const category of commandCategories) {
-        expect(typeof category.title).toBe('string');
-        expect(Array.isArray(category.commands)).toBe(true);
-
-        for (const command of category.commands) {
-          expect(commandValues).toContain(command);
-          expect(seen.has(command)).toBe(false);
-          seen.add(command);
-        }
-      }
-
-      expect(seen.size).toBe(commandValues.length);
-    });
-  });
-});

packages/cli/src/config/keyBindings.ts

@@ -1,488 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Command enum for all available keyboard shortcuts
- */
-export enum Command {
-  // Basic Controls
-  RETURN = 'basic.confirm',
-  ESCAPE = 'basic.cancel',
-  QUIT = 'basic.quit',
-  EXIT = 'basic.exit',
-
-  // Cursor Movement
-  HOME = 'cursor.home',
-  END = 'cursor.end',
-  MOVE_UP = 'cursor.up',
-  MOVE_DOWN = 'cursor.down',
-  MOVE_LEFT = 'cursor.left',
-  MOVE_RIGHT = 'cursor.right',
-  MOVE_WORD_LEFT = 'cursor.wordLeft',
-  MOVE_WORD_RIGHT = 'cursor.wordRight',
-
-  // Editing
-  KILL_LINE_RIGHT = 'edit.deleteRightAll',
-  KILL_LINE_LEFT = 'edit.deleteLeftAll',
-  CLEAR_INPUT = 'edit.clear',
-  DELETE_WORD_BACKWARD = 'edit.deleteWordLeft',
-  DELETE_WORD_FORWARD = 'edit.deleteWordRight',
-  DELETE_CHAR_LEFT = 'edit.deleteLeft',
-  DELETE_CHAR_RIGHT = 'edit.deleteRight',
-  UNDO = 'edit.undo',
-  REDO = 'edit.redo',
-
-  // Scrolling
-  SCROLL_UP = 'scroll.up',
-  SCROLL_DOWN = 'scroll.down',
-  SCROLL_HOME = 'scroll.home',
-  SCROLL_END = 'scroll.end',
-  PAGE_UP = 'scroll.pageUp',
-  PAGE_DOWN = 'scroll.pageDown',
-
-  // History & Search
-  HISTORY_UP = 'history.previous',
-  HISTORY_DOWN = 'history.next',
-  REVERSE_SEARCH = 'history.search.start',
-  SUBMIT_REVERSE_SEARCH = 'history.search.submit',
-  ACCEPT_SUGGESTION_REVERSE_SEARCH = 'history.search.accept',
-  REWIND = 'history.rewind',
-
-  // Navigation
-  NAVIGATION_UP = 'nav.up',
-  NAVIGATION_DOWN = 'nav.down',
-  DIALOG_NAVIGATION_UP = 'nav.dialog.up',
-  DIALOG_NAVIGATION_DOWN = 'nav.dialog.down',
-  DIALOG_NEXT = 'nav.dialog.next',
-  DIALOG_PREV = 'nav.dialog.previous',
-
-  // Suggestions & Completions
-  ACCEPT_SUGGESTION = 'suggest.accept',
-  COMPLETION_UP = 'suggest.focusPrevious',
-  COMPLETION_DOWN = 'suggest.focusNext',
-  EXPAND_SUGGESTION = 'suggest.expand',
-  COLLAPSE_SUGGESTION = 'suggest.collapse',
-
-  // Text Input
-  SUBMIT = 'input.submit',
-  NEWLINE = 'input.newline',
-  OPEN_EXTERNAL_EDITOR = 'input.openExternalEditor',
-  PASTE_CLIPBOARD = 'input.paste',
-
-  BACKGROUND_SHELL_ESCAPE = 'backgroundShellEscape',
-  BACKGROUND_SHELL_SELECT = 'backgroundShellSelect',
-  TOGGLE_BACKGROUND_SHELL = 'toggleBackgroundShell',
-  TOGGLE_BACKGROUND_SHELL_LIST = 'toggleBackgroundShellList',
-  KILL_BACKGROUND_SHELL = 'backgroundShell.kill',
-  UNFOCUS_BACKGROUND_SHELL = 'backgroundShell.unfocus',
-  UNFOCUS_BACKGROUND_SHELL_LIST = 'backgroundShell.listUnfocus',
-  SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING = 'backgroundShell.unfocusWarning',
-  SHOW_SHELL_INPUT_UNFOCUS_WARNING = 'shellInput.unfocusWarning',
-
-  // App Controls
-  SHOW_ERROR_DETAILS = 'app.showErrorDetails',
-  SHOW_FULL_TODOS = 'app.showFullTodos',
-  SHOW_IDE_CONTEXT_DETAIL = 'app.showIdeContextDetail',
-  TOGGLE_MARKDOWN = 'app.toggleMarkdown',
-  TOGGLE_COPY_MODE = 'app.toggleCopyMode',
-  TOGGLE_YOLO = 'app.toggleYolo',
-  CYCLE_APPROVAL_MODE = 'app.cycleApprovalMode',
-  SHOW_MORE_LINES = 'app.showMoreLines',
-  EXPAND_PASTE = 'app.expandPaste',
-  FOCUS_SHELL_INPUT = 'app.focusShellInput',
-  UNFOCUS_SHELL_INPUT = 'app.unfocusShellInput',
-  CLEAR_SCREEN = 'app.clearScreen',
-  RESTART_APP = 'app.restart',
-  SUSPEND_APP = 'app.suspend',
-}
-
-/**
- * Data-driven key binding structure for user configuration
- */
-export interface KeyBinding {
-  /** The key name (e.g., 'a', 'return', 'tab', 'escape') */
-  key: string;
-  /** Shift key requirement: true=must be pressed, false=must not be pressed, undefined=ignore */
-  shift?: boolean;
-  /** Alt/Option key requirement: true=must be pressed, false=must not be pressed, undefined=ignore */
-  alt?: boolean;
-  /** Control key requirement: true=must be pressed, false=must not be pressed, undefined=ignore */
-  ctrl?: boolean;
-  /** Command/Windows/Super key requirement: true=must be pressed, false=must not be pressed, undefined=ignore */
-  cmd?: boolean;
-}
-
-/**
- * Configuration type mapping commands to their key bindings
- */
-export type KeyBindingConfig = {
-  readonly [C in Command]: readonly KeyBinding[];
-};
-
-/**
- * Default key binding configuration
- * Matches the original hard-coded logic exactly
- */
-export const defaultKeyBindings: KeyBindingConfig = {
-  // Basic Controls
-  [Command.RETURN]: [{ key: 'return' }],
-  [Command.ESCAPE]: [{ key: 'escape' }, { key: '[', ctrl: true }],
-  [Command.QUIT]: [{ key: 'c', ctrl: true }],
-  [Command.EXIT]: [{ key: 'd', ctrl: true }],
-
-  // Cursor Movement
-  [Command.HOME]: [{ key: 'a', ctrl: true }, { key: 'home' }],
-  [Command.END]: [{ key: 'e', ctrl: true }, { key: 'end' }],
-  [Command.MOVE_UP]: [{ key: 'up' }],
-  [Command.MOVE_DOWN]: [{ key: 'down' }],
-  [Command.MOVE_LEFT]: [{ key: 'left' }],
-  [Command.MOVE_RIGHT]: [{ key: 'right' }, { key: 'f', ctrl: true }],
-  [Command.MOVE_WORD_LEFT]: [
-    { key: 'left', ctrl: true },
-    { key: 'left', alt: true },
-    { key: 'b', alt: true },
-  ],
-  [Command.MOVE_WORD_RIGHT]: [
-    { key: 'right', ctrl: true },
-    { key: 'right', alt: true },
-    { key: 'f', alt: true },
-  ],
-
-  // Editing
-  [Command.KILL_LINE_RIGHT]: [{ key: 'k', ctrl: true }],
-  [Command.KILL_LINE_LEFT]: [{ key: 'u', ctrl: true }],
-  [Command.CLEAR_INPUT]: [{ key: 'c', ctrl: true }],
-  [Command.DELETE_WORD_BACKWARD]: [
-    { key: 'backspace', ctrl: true },
-    { key: 'backspace', alt: true },
-    { key: 'w', ctrl: true },
-  ],
-  [Command.DELETE_WORD_FORWARD]: [
-    { key: 'delete', ctrl: true },
-    { key: 'delete', alt: true },
-    { key: 'd', alt: true },
-  ],
-  [Command.DELETE_CHAR_LEFT]: [{ key: 'backspace' }, { key: 'h', ctrl: true }],
-  [Command.DELETE_CHAR_RIGHT]: [{ key: 'delete' }, { key: 'd', ctrl: true }],
-  [Command.UNDO]: [
-    { key: 'z', cmd: true },
-    { key: 'z', alt: true },
-  ],
-  [Command.REDO]: [
-    { key: 'z', ctrl: true, shift: true },
-    { key: 'z', cmd: true, shift: true },
-    { key: 'z', alt: true, shift: true },
-  ],
-
-  // Scrolling
-  [Command.SCROLL_UP]: [{ key: 'up', shift: true }],
-  [Command.SCROLL_DOWN]: [{ key: 'down', shift: true }],
-  [Command.SCROLL_HOME]: [
-    { key: 'home', ctrl: true },
-    { key: 'home', shift: true },
-  ],
-  [Command.SCROLL_END]: [
-    { key: 'end', ctrl: true },
-    { key: 'end', shift: true },
-  ],
-  [Command.PAGE_UP]: [{ key: 'pageup' }],
-  [Command.PAGE_DOWN]: [{ key: 'pagedown' }],
-
-  // History & Search
-  [Command.HISTORY_UP]: [{ key: 'p', ctrl: true }],
-  [Command.HISTORY_DOWN]: [{ key: 'n', ctrl: true }],
-  [Command.REVERSE_SEARCH]: [{ key: 'r', ctrl: true }],
-  [Command.REWIND]: [{ key: 'double escape' }], // for documentation only
-  [Command.SUBMIT_REVERSE_SEARCH]: [{ key: 'return' }],
-  [Command.ACCEPT_SUGGESTION_REVERSE_SEARCH]: [{ key: 'tab' }],
-
-  // Navigation
-  [Command.NAVIGATION_UP]: [{ key: 'up' }],
-  [Command.NAVIGATION_DOWN]: [{ key: 'down' }],
-  // Navigation shortcuts appropriate for dialogs where we do not need to accept
-  // text input.
-  [Command.DIALOG_NAVIGATION_UP]: [{ key: 'up' }, { key: 'k' }],
-  [Command.DIALOG_NAVIGATION_DOWN]: [{ key: 'down' }, { key: 'j' }],
-  [Command.DIALOG_NEXT]: [{ key: 'tab' }],
-  [Command.DIALOG_PREV]: [{ key: 'tab', shift: true }],
-
-  // Suggestions & Completions
-  [Command.ACCEPT_SUGGESTION]: [{ key: 'tab' }, { key: 'return' }],
-  [Command.COMPLETION_UP]: [{ key: 'up' }, { key: 'p', ctrl: true }],
-  [Command.COMPLETION_DOWN]: [{ key: 'down' }, { key: 'n', ctrl: true }],
-  [Command.EXPAND_SUGGESTION]: [{ key: 'right' }],
-  [Command.COLLAPSE_SUGGESTION]: [{ key: 'left' }],
-
-  // Text Input
-  // Must also exclude shift to allow shift+enter for newline
-  [Command.SUBMIT]: [{ key: 'return' }],
-  [Command.NEWLINE]: [
-    { key: 'return', ctrl: true },
-    { key: 'return', cmd: true },
-    { key: 'return', alt: true },
-    { key: 'return', shift: true },
-    { key: 'j', ctrl: true },
-  ],
-  [Command.OPEN_EXTERNAL_EDITOR]: [{ key: 'x', ctrl: true }],
-  [Command.PASTE_CLIPBOARD]: [
-    { key: 'v', ctrl: true },
-    { key: 'v', cmd: true },
-    { key: 'v', alt: true },
-  ],
-
-  // App Controls
-  [Command.SHOW_ERROR_DETAILS]: [{ key: 'f12' }],
-  [Command.SHOW_FULL_TODOS]: [{ key: 't', ctrl: true }],
-  [Command.SHOW_IDE_CONTEXT_DETAIL]: [{ key: 'g', ctrl: true }],
-  [Command.TOGGLE_MARKDOWN]: [{ key: 'm', alt: true }],
-  [Command.TOGGLE_COPY_MODE]: [{ key: 's', ctrl: true }],
-  [Command.TOGGLE_YOLO]: [{ key: 'y', ctrl: true }],
-  [Command.CYCLE_APPROVAL_MODE]: [{ key: 'tab', shift: true }],
-  [Command.TOGGLE_BACKGROUND_SHELL]: [{ key: 'b', ctrl: true }],
-  [Command.TOGGLE_BACKGROUND_SHELL_LIST]: [{ key: 'l', ctrl: true }],
-  [Command.KILL_BACKGROUND_SHELL]: [{ key: 'k', ctrl: true }],
-  [Command.UNFOCUS_BACKGROUND_SHELL]: [{ key: 'tab', shift: true }],
-  [Command.UNFOCUS_BACKGROUND_SHELL_LIST]: [{ key: 'tab' }],
-  [Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING]: [{ key: 'tab' }],
-  [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]: [{ key: 'tab' }],
-  [Command.BACKGROUND_SHELL_SELECT]: [{ key: 'return' }],
-  [Command.BACKGROUND_SHELL_ESCAPE]: [{ key: 'escape' }],
-  [Command.SHOW_MORE_LINES]: [{ key: 'o', ctrl: true }],
-  [Command.EXPAND_PASTE]: [{ key: 'o', ctrl: true }],
-  [Command.FOCUS_SHELL_INPUT]: [{ key: 'tab' }],
-  [Command.UNFOCUS_SHELL_INPUT]: [{ key: 'tab', shift: true }],
-  [Command.CLEAR_SCREEN]: [{ key: 'l', ctrl: true }],
-  [Command.RESTART_APP]: [{ key: 'r' }, { key: 'r', shift: true }],
-  [Command.SUSPEND_APP]: [{ key: 'z', ctrl: true }],
-};
-
-interface CommandCategory {
-  readonly title: string;
-  readonly commands: readonly Command[];
-}
-
-/**
- * Presentation metadata for grouping commands in documentation or UI.
- */
-export const commandCategories: readonly CommandCategory[] = [
-  {
-    title: 'Basic Controls',
-    commands: [Command.RETURN, Command.ESCAPE, Command.QUIT, Command.EXIT],
-  },
-  {
-    title: 'Cursor Movement',
-    commands: [
-      Command.HOME,
-      Command.END,
-      Command.MOVE_UP,
-      Command.MOVE_DOWN,
-      Command.MOVE_LEFT,
-      Command.MOVE_RIGHT,
-      Command.MOVE_WORD_LEFT,
-      Command.MOVE_WORD_RIGHT,
-    ],
-  },
-  {
-    title: 'Editing',
-    commands: [
-      Command.KILL_LINE_RIGHT,
-      Command.KILL_LINE_LEFT,
-      Command.CLEAR_INPUT,
-      Command.DELETE_WORD_BACKWARD,
-      Command.DELETE_WORD_FORWARD,
-      Command.DELETE_CHAR_LEFT,
-      Command.DELETE_CHAR_RIGHT,
-      Command.UNDO,
-      Command.REDO,
-    ],
-  },
-  {
-    title: 'Scrolling',
-    commands: [
-      Command.SCROLL_UP,
-      Command.SCROLL_DOWN,
-      Command.SCROLL_HOME,
-      Command.SCROLL_END,
-      Command.PAGE_UP,
-      Command.PAGE_DOWN,
-    ],
-  },
-  {
-    title: 'History & Search',
-    commands: [
-      Command.HISTORY_UP,
-      Command.HISTORY_DOWN,
-      Command.REVERSE_SEARCH,
-      Command.SUBMIT_REVERSE_SEARCH,
-      Command.ACCEPT_SUGGESTION_REVERSE_SEARCH,
-      Command.REWIND,
-    ],
-  },
-  {
-    title: 'Navigation',
-    commands: [
-      Command.NAVIGATION_UP,
-      Command.NAVIGATION_DOWN,
-      Command.DIALOG_NAVIGATION_UP,
-      Command.DIALOG_NAVIGATION_DOWN,
-      Command.DIALOG_NEXT,
-      Command.DIALOG_PREV,
-    ],
-  },
-  {
-    title: 'Suggestions & Completions',
-    commands: [
-      Command.ACCEPT_SUGGESTION,
-      Command.COMPLETION_UP,
-      Command.COMPLETION_DOWN,
-      Command.EXPAND_SUGGESTION,
-      Command.COLLAPSE_SUGGESTION,
-    ],
-  },
-  {
-    title: 'Text Input',
-    commands: [
-      Command.SUBMIT,
-      Command.NEWLINE,
-      Command.OPEN_EXTERNAL_EDITOR,
-      Command.PASTE_CLIPBOARD,
-    ],
-  },
-  {
-    title: 'App Controls',
-    commands: [
-      Command.SHOW_ERROR_DETAILS,
-      Command.SHOW_FULL_TODOS,
-      Command.SHOW_IDE_CONTEXT_DETAIL,
-      Command.TOGGLE_MARKDOWN,
-      Command.TOGGLE_COPY_MODE,
-      Command.TOGGLE_YOLO,
-      Command.CYCLE_APPROVAL_MODE,
-      Command.SHOW_MORE_LINES,
-      Command.EXPAND_PASTE,
-      Command.TOGGLE_BACKGROUND_SHELL,
-      Command.TOGGLE_BACKGROUND_SHELL_LIST,
-      Command.KILL_BACKGROUND_SHELL,
-      Command.BACKGROUND_SHELL_SELECT,
-      Command.BACKGROUND_SHELL_ESCAPE,
-      Command.UNFOCUS_BACKGROUND_SHELL,
-      Command.UNFOCUS_BACKGROUND_SHELL_LIST,
-      Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING,
-      Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING,
-      Command.FOCUS_SHELL_INPUT,
-      Command.UNFOCUS_SHELL_INPUT,
-      Command.CLEAR_SCREEN,
-      Command.RESTART_APP,
-      Command.SUSPEND_APP,
-    ],
-  },
-];
-
-/**
- * Human-readable descriptions for each command, used in docs/tooling.
- */
-export const commandDescriptions: Readonly<Record<Command, string>> = {
-  // Basic Controls
-  [Command.RETURN]: 'Confirm the current selection or choice.',
-  [Command.ESCAPE]: 'Dismiss dialogs or cancel the current focus.',
-  [Command.QUIT]:
-    'Cancel the current request or quit the CLI when input is empty.',
-  [Command.EXIT]: 'Exit the CLI when the input buffer is empty.',
-
-  // Cursor Movement
-  [Command.HOME]: 'Move the cursor to the start of the line.',
-  [Command.END]: 'Move the cursor to the end of the line.',
-  [Command.MOVE_UP]: 'Move the cursor up one line.',
-  [Command.MOVE_DOWN]: 'Move the cursor down one line.',
-  [Command.MOVE_LEFT]: 'Move the cursor one character to the left.',
-  [Command.MOVE_RIGHT]: 'Move the cursor one character to the right.',
-  [Command.MOVE_WORD_LEFT]: 'Move the cursor one word to the left.',
-  [Command.MOVE_WORD_RIGHT]: 'Move the cursor one word to the right.',
-
-  // Editing
-  [Command.KILL_LINE_RIGHT]: 'Delete from the cursor to the end of the line.',
-  [Command.KILL_LINE_LEFT]: 'Delete from the cursor to the start of the line.',
-  [Command.CLEAR_INPUT]: 'Clear all text in the input field.',
-  [Command.DELETE_WORD_BACKWARD]: 'Delete the previous word.',
-  [Command.DELETE_WORD_FORWARD]: 'Delete the next word.',
-  [Command.DELETE_CHAR_LEFT]: 'Delete the character to the left.',
-  [Command.DELETE_CHAR_RIGHT]: 'Delete the character to the right.',
-  [Command.UNDO]: 'Undo the most recent text edit.',
-  [Command.REDO]: 'Redo the most recent undone text edit.',
-
-  // Scrolling
-  [Command.SCROLL_UP]: 'Scroll content up.',
-  [Command.SCROLL_DOWN]: 'Scroll content down.',
-  [Command.SCROLL_HOME]: 'Scroll to the top.',
-  [Command.SCROLL_END]: 'Scroll to the bottom.',
-  [Command.PAGE_UP]: 'Scroll up by one page.',
-  [Command.PAGE_DOWN]: 'Scroll down by one page.',
-
-  // History & Search
-  [Command.HISTORY_UP]: 'Show the previous entry in history.',
-  [Command.HISTORY_DOWN]: 'Show the next entry in history.',
-  [Command.REVERSE_SEARCH]: 'Start reverse search through history.',
-  [Command.SUBMIT_REVERSE_SEARCH]: 'Submit the selected reverse-search match.',
-  [Command.ACCEPT_SUGGESTION_REVERSE_SEARCH]:
-    'Accept a suggestion while reverse searching.',
-  [Command.REWIND]: 'Browse and rewind previous interactions.',
-
-  // Navigation
-  [Command.NAVIGATION_UP]: 'Move selection up in lists.',
-  [Command.NAVIGATION_DOWN]: 'Move selection down in lists.',
-  [Command.DIALOG_NAVIGATION_UP]: 'Move up within dialog options.',
-  [Command.DIALOG_NAVIGATION_DOWN]: 'Move down within dialog options.',
-  [Command.DIALOG_NEXT]: 'Move to the next item or question in a dialog.',
-  [Command.DIALOG_PREV]: 'Move to the previous item or question in a dialog.',
-
-  // Suggestions & Completions
-  [Command.ACCEPT_SUGGESTION]: 'Accept the inline suggestion.',
-  [Command.COMPLETION_UP]: 'Move to the previous completion option.',
-  [Command.COMPLETION_DOWN]: 'Move to the next completion option.',
-  [Command.EXPAND_SUGGESTION]: 'Expand an inline suggestion.',
-  [Command.COLLAPSE_SUGGESTION]: 'Collapse an inline suggestion.',
-
-  // Text Input
-  [Command.SUBMIT]: 'Submit the current prompt.',
-  [Command.NEWLINE]: 'Insert a newline without submitting.',
-  [Command.OPEN_EXTERNAL_EDITOR]:
-    'Open the current prompt or the plan in an external editor.',
-  [Command.PASTE_CLIPBOARD]: 'Paste from the clipboard.',
-
-  // App Controls
-  [Command.SHOW_ERROR_DETAILS]: 'Toggle detailed error information.',
-  [Command.SHOW_FULL_TODOS]: 'Toggle the full TODO list.',
-  [Command.SHOW_IDE_CONTEXT_DETAIL]: 'Show IDE context details.',
-  [Command.TOGGLE_MARKDOWN]: 'Toggle Markdown rendering.',
-  [Command.TOGGLE_COPY_MODE]: 'Toggle copy mode when in alternate buffer mode.',
-  [Command.TOGGLE_YOLO]: 'Toggle YOLO (auto-approval) mode for tool calls.',
-  [Command.CYCLE_APPROVAL_MODE]:
-    'Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). Plan mode is skipped when the agent is busy.',
-  [Command.SHOW_MORE_LINES]:
-    'Expand and collapse blocks of content when not in alternate buffer mode.',
-  [Command.EXPAND_PASTE]:
-    'Expand or collapse a paste placeholder when cursor is over placeholder.',
-  [Command.BACKGROUND_SHELL_SELECT]:
-    'Confirm selection in background shell list.',
-  [Command.BACKGROUND_SHELL_ESCAPE]: 'Dismiss background shell list.',
-  [Command.TOGGLE_BACKGROUND_SHELL]:
-    'Toggle current background shell visibility.',
-  [Command.TOGGLE_BACKGROUND_SHELL_LIST]: 'Toggle background shell list.',
-  [Command.KILL_BACKGROUND_SHELL]: 'Kill the active background shell.',
-  [Command.UNFOCUS_BACKGROUND_SHELL]:
-    'Move focus from background shell to Gemini.',
-  [Command.UNFOCUS_BACKGROUND_SHELL_LIST]:
-    'Move focus from background shell list to Gemini.',
-  [Command.SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING]:
-    'Show warning when trying to move focus away from background shell.',
-  [Command.SHOW_SHELL_INPUT_UNFOCUS_WARNING]:
-    'Show warning when trying to move focus away from shell input.',
-  [Command.FOCUS_SHELL_INPUT]: 'Move focus from Gemini to the active shell.',
-  [Command.UNFOCUS_SHELL_INPUT]: 'Move focus from the shell back to Gemini.',
-  [Command.CLEAR_SCREEN]: 'Clear the terminal screen and redraw the UI.',
-  [Command.RESTART_APP]: 'Restart the application.',
-  [Command.SUSPEND_APP]: 'Suspend the CLI and move it to the background.',
-};