|
| 1 | +## Summary |
| 2 | + |
| 3 | +This PR implements a seamless migration path for extensions to move to a new |
| 4 | +repository and optionally change their name without stranding existing users. |
| 5 | + |
| 6 | +When an extension author sets the `migratedTo` field in their |
| 7 | +`gemini-extension.json` and publishes an update to their old repository, the CLI |
| 8 | +will detect this during the next update check. The CLI will then automatically |
| 9 | +download the extension from the new repository, explicitly warn the user about |
| 10 | +the migration (and any renaming) during the consent step, and seamlessly migrate |
| 11 | +the installation and enablement status while cleaning up the old installation. |
| 12 | + |
| 13 | +## Details |
| 14 | + |
| 15 | +- **Configuration:** Added `migratedTo` property to `ExtensionConfig` and |
| 16 | + `GeminiCLIExtension` to track the new repository URL. |
| 17 | +- **Update checking & downloading:** Updated `checkForExtensionUpdate` and |
| 18 | + `updateExtension` to inspect the `migratedTo` field. If present, the CLI |
| 19 | + queries the new repository URL for an update and swaps the installation source |
| 20 | + so the update resolves from the new location. |
| 21 | +- **Migration & renaming logic (`ExtensionManager`):** |
| 22 | + - `installOrUpdateExtension` now fully supports renaming. It transfers global |
| 23 | + and workspace enablement states from the old extension name to the new one |
| 24 | + and deletes the old extension directory. |
| 25 | + - Added safeguards to block renaming if the new name conflicts with a |
| 26 | + different, already-installed extension or if the destination directory |
| 27 | + already exists. |
| 28 | + - Exposed `getEnablementManager()` to `ExtensionManager` for better typing |
| 29 | + during testing. |
| 30 | +- **Consent messaging:** Refactored `maybeRequestConsentOrFail` to compute an |
| 31 | + `isMigrating` flag (by detecting a change in the installation source). The |
| 32 | + `extensionConsentString` output now explicitly informs users with messages |
| 33 | + like: _"Migrating extension 'old-name' to a new repository, renaming to |
| 34 | + 'new-name', and installing updates."_ |
| 35 | +- **Documentation:** Documented the `migratedTo` field in |
| 36 | + `docs/extensions/reference.md` and added a comprehensive guide in |
| 37 | + `docs/extensions/releasing.md` explaining how extension maintainers can |
| 38 | + transition users using this feature. |
| 39 | +- **Testing:** Added extensive unit tests across `extension-manager.test.ts`, |
| 40 | + `consent.test.ts`, `github.test.ts`, and `update.test.ts` to cover the new |
| 41 | + migration and renaming logic. |
| 42 | + |
| 43 | +## Related issues |
| 44 | + |
| 45 | +N/A |
| 46 | + |
| 47 | +## How to validate |
| 48 | + |
| 49 | +1. **Unit tests:** Run all related tests to confirm everything passes: |
| 50 | + ```bash |
| 51 | + npm run test -w @google/gemini-cli -- src/config/extensions/github.test.ts |
| 52 | + npm run test -w @google/gemini-cli -- src/config/extensions/update.test.ts |
| 53 | + npm run test -w @google/gemini-cli -- src/config/extensions/consent.test.ts |
| 54 | + npm run test -w @google/gemini-cli -- src/config/extension-manager.test.ts |
| 55 | + ``` |
| 56 | +2. **End-to-end migration test:** |
| 57 | + - Install a local or git extension. |
| 58 | + - Update its `gemini-extension.json` to include a `migratedTo` field pointing |
| 59 | + to a _different_ test repository. |
| 60 | + - Run `gemini extensions check` to confirm it detects the update from the new |
| 61 | + source. |
| 62 | + - Run `gemini extensions update <extension>`. |
| 63 | + - Verify that the consent prompt explicitly mentions the migration. |
| 64 | + - Verify that the new extension is installed, the old directory is deleted, |
| 65 | + and its enablement status carried over. |
0 commit comments