Add support for updating extension sources and names

[chrstnb]

Summary

This PR implements a seamless migration path for extensions to move to a new repository and optionally change their name without stranding existing users.

When an extension author sets the migratedTo field in their gemini-extension.json and publishes an update to their old repository, the CLI will detect this during the next update check. The CLI will then automatically download the extension from the new repository, explicitly warn the user about the migration (and any renaming) during the consent step, and seamlessly migrate the installation and enablement status while cleaning up the old installation.

Details

• Configuration: Added migratedTo property to ExtensionConfig and GeminiCLIExtension to track the new repository URL.
• Update checking & downloading: Updated checkForExtensionUpdate and updateExtension to inspect the migratedTo field. If present, the CLI queries the new repository URL for an update and swaps the installation source so the update resolves from the new location.
• Migration & renaming logic (ExtensionManager):
  • installOrUpdateExtension now fully supports renaming. It transfers global and workspace enablement states from the old extension name to the new one and deletes the old extension directory.
  • Added safeguards to block renaming if the new name conflicts with a different, already-installed extension or if the destination directory already exists.
  • Exposed getEnablementManager() to ExtensionManager for better typing during testing.
• Consent messaging: Refactored maybeRequestConsentOrFail to compute an isMigrating flag (by detecting a change in the installation source). The extensionConsentString output now explicitly informs users with messages like: "Migrating extension 'old-name' to a new repository, renaming to 'new-name', and installing updates."
• Documentation: Documented the migratedTo field in docs/extensions/reference.md and added a comprehensive guide in docs/extensions/releasing.md explaining how extension maintainers can transition users using this feature.
• Testing: Added extensive unit tests across extension-manager.test.ts, consent.test.ts, github.test.ts, and update.test.ts to cover the new migration and renaming logic.

Related issues

Fixes #21700

How to validate

1. Unit tests: Run all related tests to confirm everything passes:

   npm run test -w @google/gemini-cli -- src/config/extensions/github.test.ts
   npm run test -w @google/gemini-cli -- src/config/extensions/update.test.ts
   npm run test -w @google/gemini-cli -- src/config/extensions/consent.test.ts
   npm run test -w @google/gemini-cli -- src/config/extension-manager.test.ts

2. End-to-end migration test:
   • Install a local or git extension.
   • Update its gemini-extension.json to include a migratedTo field pointing to a different test repository.
   • Run gemini extensions check to confirm it detects the update from the new source.
   • Run gemini extensions update <extension>.
   • Verify that the consent prompt explicitly mentions the migration.
   • Verify that the new extension is installed, the old directory is deleted, and its enablement status carried over.

Pre-Merge Checklist

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

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust mechanism for managing extension migrations and renames within the Gemini CLI. It allows extension authors to specify a new repository URL and optionally a new name, enabling a smooth transition for existing users. The CLI will automatically detect these changes, download updates from the new source, migrate installation details, and update enablement statuses, all while providing clear consent prompts to the user. This significantly improves the flexibility and maintainability of extensions by supporting changes in their underlying distribution.

Highlights

• Extension Migration Support: Introduced a migratedTo field in extension configuration (gemini-extension.json) to facilitate seamless repository transitions for extensions.
• Automatic Update Source Switching: Implemented automatic detection and handling of extension migrations, including downloading updates from the new migratedTo source.
• Extension Renaming Capability: Enabled support for renaming extensions during an update, ensuring existing users are not stranded when an extension changes its name.
• Enablement Status Transfer: Ensured global and workspace enablement statuses are preserved and automatically transferred when an extension is renamed.
• Enhanced User Consent: Updated user consent prompts to clearly communicate extension migrations and renames to the user before applying changes.
• Comprehensive Testing and Documentation: Added extensive unit tests covering migration and renaming logic, and updated documentation to guide extension maintainers on using these new features.

Changelog

• docs/extensions/reference.md
  • Updated extension manifest example to include the migratedTo property.
  • Documented the purpose and usage of the new migratedTo field.
• docs/extensions/releasing.md
  • Added a new comprehensive guide detailing the process for migrating an extension repository.
• packages/cli/src/config/extension-manager.test.ts
  • Added tests for extension renaming functionality during updates.
  • Included tests to verify enablement status transfer during renaming.
  • Added a test to ensure renaming conflicts with existing extensions are prevented.
• packages/cli/src/config/extension-manager.ts
  • Exposed getEnablementManager for better testing and internal access.
  • Modified installOrUpdateExtension to support extension renaming and migration logic.
  • Implemented checks to prevent renaming to an already existing extension name or directory.
  • Added logic to transfer global and workspace enablement states during a rename.
  • Updated loadExtension to include the migratedTo property in the loaded extension object.
• packages/cli/src/config/extension.ts
  • Added the migratedTo property to the ExtensionConfig interface.
• packages/cli/src/config/extensions/consent.test.ts
  • Added a test case to verify consent prompt behavior during extension migration.
• packages/cli/src/config/extensions/consent.ts
  • Updated extensionConsentString to generate specific messages for extension migrations and renames.
  • Modified maybeRequestConsentOrFail to pass migration status and previous name to the consent string generator.
• packages/cli/src/config/extensions/github.test.ts
  • Added a test to confirm checkForExtensionUpdate correctly checks the migratedTo source.
• packages/cli/src/config/extensions/github.ts
  • Modified checkForExtensionUpdate to prioritize checking the migratedTo source for updates.
• packages/cli/src/config/extensions/update.test.ts
  • Added a test for source migration when migratedTo is set and an update is available.
• packages/cli/src/config/extensions/update.ts
  • Updated updateExtension to modify the installation source to the migratedTo URL if an update is found there.
• packages/core/src/config/config.ts
  • Added the migratedTo property to the GeminiCLIExtension interface.

Activity

• The author, chrstnb, initiated this pull request to address issue Add support for renaming extension repos #21700, focusing on enabling seamless extension migrations and renames.
• Extensive unit tests were added across multiple files (extension-manager.test.ts, consent.test.ts, github.test.ts, update.test.ts) to validate the new functionality.
• Detailed validation steps, including unit test commands and an end-to-end migration test, were provided in the PR description for reviewers.
• Documentation was updated in docs/extensions/reference.md and docs/extensions/releasing.md to guide extension maintainers on using the new migratedTo feature.
• A pre-merge checklist was included, outlining necessary checks for documentation, tests, breaking changes, and platform validation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +3.68 kB (+0.01%)

Total Size: 26.1 MB

Filename	Size	Change
./bundle/gemini.js	25.7 MB	+3.68 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a well-implemented feature for extension migration and renaming. The changes are comprehensive, covering configuration, update logic, installation, user consent, and testing. The code is generally robust and handles edge cases like name conflicts and preserving enablement state.

_{Note: Security Review is unavailable for this PR.}

[alisa-alisa]

do we need to submit this file?

[alisa-alisa]

please ensure if you want pr-description.md file to be submitted.