#2131: improve auto completion for ide upgrade mode

CHANGELOG.adoc

@@ -6,6 +6,7 @@ This file documents all notable changes to https://github.com/devonfw/IDEasy[IDE
 
 Release with new features and bugfixes:
 
+* https://github.com/devonfw/IDEasy/issues/2131[#2131]: Improve `ide upgrade --mode=` auto-completion
 * https://github.com/devonfw/IDEasy/issues/2100[#2100]: Fix Python not available for Mac x64
 
 The full list of changes for this release can be found in https://github.com/devonfw/IDEasy/milestone/48?closed=1[milestone 2026.08.001].

cli/src/main/java/com/devonfw/tools/ide/commandlet/UpgradeCommandlet.java

@@ -28,7 +28,7 @@ public UpgradeCommandlet(IdeContext context) {
 
     super(context);
     addKeyword(getName());
-    this.mode = add(new EnumProperty<>("--mode", false, null, UpgradeMode.class));
+    this.mode = add(new UpgradeModeProperty());
   }
 
   @Override

cli/src/main/java/com/devonfw/tools/ide/commandlet/UpgradeModeProperty.java

@@ -0,0 +1,31 @@
+package com.devonfw.tools.ide.commandlet;
+
+import java.util.Locale;
+
+import com.devonfw.tools.ide.completion.CompletionCandidateCollector;
+import com.devonfw.tools.ide.context.IdeContext;
+import com.devonfw.tools.ide.property.EnumProperty;
+
+/**
+ * {@link EnumProperty} for {@link UpgradeMode} that controls auto-completion of the {@code --mode} option.
+ */
+public class UpgradeModeProperty extends EnumProperty<UpgradeMode> {
+
+  /**
+   * The constructor.
+   */
+  public UpgradeModeProperty() {
+    super("--mode", false, null, UpgradeMode.class);
+  }
+
+  @Override
+  protected void completeValue(String arg, IdeContext context, Commandlet commandlet, CompletionCandidateCollector collector) {
+
+    for (UpgradeMode mode : UpgradeMode.values()) {
+      String text = mode.name().toLowerCase(Locale.ROOT);
+      if (text.startsWith(arg)) {
+        collector.add(text, null, this, commandlet);
+      }
+    }
+  }
+}

cli/src/main/package/functions

@@ -254,9 +254,10 @@ _ide_create_project()
   done
 }
 
-# remove ":" from word breaks so completion keeps arguments like "dependency:list" together.
+# remove ":" and "=" from word breaks so completion keeps arguments like "dependency:list" and "--mode="
 if [ -n "${COMP_WORDBREAKS:-}" ]; then
   COMP_WORDBREAKS=${COMP_WORDBREAKS//:}
+  COMP_WORDBREAKS=${COMP_WORDBREAKS//=}
 fi
 
 _ide_completion()

cli/src/test/java/com/devonfw/tools/ide/commandlet/UpgradeCommandletTest.java

@@ -3,10 +3,16 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
 
 import com.devonfw.tools.ide.cli.CliException;
 import com.devonfw.tools.ide.cli.CliOfflineException;
+import com.devonfw.tools.ide.completion.CompletionCandidate;
+import com.devonfw.tools.ide.completion.CompletionCandidateCollector;
+import com.devonfw.tools.ide.completion.CompletionCandidateCollectorDefault;
 import com.devonfw.tools.ide.context.AbstractIdeContextTest;
+import com.devonfw.tools.ide.context.IdeContext;
 import com.devonfw.tools.ide.context.IdeTestContext;
 import com.github.tomakehurst.wiremock.junit5.WireMockRuntimeInfo;
 import com.github.tomakehurst.wiremock.junit5.WireMockTest;
@@ -45,4 +51,37 @@ void testUpgradeWhenOffline(WireMockRuntimeInfo wmRuntimeInfo) {
     // assert
     assertThat(e).hasMessage("You are offline but Internet access is required for upgrade of IDEasy");
   }
+
+  @ParameterizedTest
+  @CsvSource({ "'',stable unstable snapshot", "u,unstable", "s,stable snapshot", "st,stable" })
+  void testUpgradeModeCompletion(String input, String expected) {
+    // arrange
+    IdeTestContext context = new IdeTestContext();
+    CompletionCandidateCollector collector = new CompletionCandidateCollectorDefault(context);
+    UpgradeModeProperty property = new UpgradeModeProperty();
+
+    // act
+    property.completeValue(input, context, new UpgradeCommandlet(context), collector);
+
+    // assert
+    assertThat(collector.getCandidates().stream().map(CompletionCandidate::text))
+        .containsExactly(expected.split(" "));
+  }
+
+  /**
+   * Test that no completion candidates are suggested for an unknown prefix.
+   */
+  @Test
+  void testUpgradeModeCompletionNoMatch() {
+    // arrange
+    IdeContext context = new IdeTestContext();
+    CompletionCandidateCollector collector = new CompletionCandidateCollectorDefault(context);
+    UpgradeModeProperty property = new UpgradeModeProperty();
+
+    // act
+    property.completeValue("ss", context, new UpgradeCommandlet(context), collector);
+
+    // assert
+    assertThat(collector.getCandidates()).isEmpty();
+  }
 }

documentation/cli.adoc

@@ -55,6 +55,7 @@ ide install «tool» [«version»]
 ```
 ide «tool» «args»
 ```
+
 This makes IDEasy a superiour tool since it can replace `mvnw` (maven wrapper), `gradlew` (gradle wrapper), `nvm` (node version manager), etc.
 Unlike these tool-specific wrapper scripts, it will even ensure that the actual command is called with the proper configuration of your project (e.g. in case of `mvn` with the `settings.xml` and `settings-security.xml` specific for your project).
 However, if you like such wrapper and IDEasy you can still use both at the same time:
@@ -75,6 +76,7 @@ Please note that the defaults are as following:
 «TOOL»_VERSION=*
 «TOOL»_EDITION=«tool»
 ```
+
 So by default you always get the latest stable version of the tool and the "standard" edition.
 Some tools support multiple editions.
 E.g. for `Eclipse` there is also a `jee` and a `cpp` edition and if you have an according license for Intellij, you can set the edition to `ultimate`.
@@ -119,6 +121,8 @@ Therefore we may have to trigger a `git pull` on the `urls` repository with the
 This can cause that the auto-completion of versions can take a few seconds sometimes.
 However, we implemented a smart caching mechanism so we do not call `git pull` again if already done a minute ago.
 
+The auto-completion also supports argument values for some commandlets, e.g. `ide upgrade --mode=` suggests valid upgrade modes such as `stable` and `snapshot`.
+
 == icd
 
 IDEasy also ships with the `icd` command that can be used as fancy improved version of the regular `cd` command: