#2180: Add *_PLUGINS_EXTRA variable to install extra IDE plugins per user

CHANGELOG.adoc

@@ -9,6 +9,7 @@ Release with new features and bugfixes:
 * https://github.com/devonfw/IDEasy/issues/2176[#2176]: Support 7z archive extraction
 * https://github.com/devonfw/IDEasy/issues/2100[#2100]: Fix Python not available for Mac x64
 * https://github.com/devonfw/IDEasy/issues/2134[#2134]: Add auto-completion for icd command
+* https://github.com/devonfw/IDEasy/issues/2180[#2180]: Add *_PLUGINS_EXTRA variable to install extra IDE plugins per user
 
 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/tool/plugin/PluginBasedCommandlet.java

@@ -12,6 +12,8 @@
 import com.devonfw.tools.ide.cli.CliException;
 import com.devonfw.tools.ide.common.Tag;
 import com.devonfw.tools.ide.context.IdeContext;
+import com.devonfw.tools.ide.environment.EnvironmentVariables;
+import com.devonfw.tools.ide.environment.VariableLine;
 import com.devonfw.tools.ide.io.FileAccess;
 import com.devonfw.tools.ide.process.ProcessContext;
 import com.devonfw.tools.ide.process.ProcessErrorHandling;
@@ -28,6 +30,9 @@ public abstract class PluginBasedCommandlet extends LocalToolCommandlet {
 
   private static final Logger LOG = LoggerFactory.getLogger(PluginBasedCommandlet.class);
 
+  /** Suffix of the tool-specific variable listing additional plugins to activate (e.g. {@code VSCODE_PLUGINS_EXTRA}). */
+  public static final String VARIABLE_SUFFIX_PLUGINS_EXTRA = "_PLUGINS_EXTRA";
+
   private ToolPlugins plugins;
 
   /** {@link FlagProperty} to force the reset and reinstallation of plugins as configured in the project settings. */
@@ -68,6 +73,8 @@ public ToolPlugins getPlugins() {
       Path userPluginsPath = getUserHomePluginsConfigPath();
       loadPluginsFromDirectory(toolPlugins, userPluginsPath);
 
+      activateExtraPlugins(toolPlugins);
+
       this.plugins = toolPlugins;
     }
 
@@ -316,4 +323,33 @@ protected void handleInstallForInactivePlugin(ToolPluginDescriptor plugin) {
 
     LOG.debug("Omitting installation of inactive plugin {} ({}).", plugin.name(), plugin.id());
   }
+
+  /**
+   * Activates the plugins configured in the tool-specific {@code «TOOL»}{@value #VARIABLE_SUFFIX_PLUGINS_EXTRA} variable (e.g.
+   * {@code VSCODE_PLUGINS_EXTRA=copilot,docker}). This allows a user to permanently opt-in to plugins that are not {@link ToolPluginDescriptor#active() active}
+   * in the project settings, without modifying the shared settings and without losing them when plugins are purged and reinstalled on IDE upgrade. Values refer
+   * to the {@link ToolPluginDescriptor#name() name} of the plugin (the filename of its {@code .properties} file) and not to the
+   * {@link ToolPluginDescriptor#id() id}. Names that do not resolve to a configured plugin are logged as a warning and skipped so that a single stale entry
+   * cannot break the entire installation.
+   *
+   * @param toolPlugins the {@link ToolPlugins} to modify.
+   */
+  private void activateExtraPlugins(ToolPlugins toolPlugins) {
+
+    String variable = EnvironmentVariables.getToolVariablePrefix(this.tool) + VARIABLE_SUFFIX_PLUGINS_EXTRA;
+    String value = this.context.getVariables().get(variable);
+    if ((value == null) || value.isBlank()) {
+      return;
+    }
+    for (String entry : VariableLine.parseArray(value)) {
+      String name = entry;
+      if (name.endsWith(IdeContext.EXT_PROPERTIES)) {
+        name = name.substring(0, name.length() - IdeContext.EXT_PROPERTIES.length());
+      }
+      if (toolPlugins.activate(name) == null) {
+        LOG.warn("Undefined plugin '{}' configured in variable {} - no file {}{} found in {} or {}.", name, variable, name, IdeContext.EXT_PROPERTIES,
+            getPluginsConfigPath(), getUserHomePluginsConfigPath());
+      }
+    }
+  }
 }

cli/src/main/java/com/devonfw/tools/ide/tool/plugin/ToolPluginDescriptor.java

@@ -81,4 +81,17 @@ private static String getString(Properties properties, String key, String legacy
     return value != null ? value.trim() : null;
   }
 
+  /**
+   * @param newActive the new value of {@link #active()}.
+   * @return this {@link ToolPluginDescriptor} if {@link #active()} already has the given value, otherwise a copy of this descriptor with all other properties
+   *     unchanged and {@link #active()} set to the given value.
+   */
+  public ToolPluginDescriptor withActive(boolean newActive) {
+
+    if (newActive == this.active) {
+      return this;
+    }
+    return new ToolPluginDescriptor(this.id, this.name, this.url, this.version, newActive, this.tags);
+  }
+
 }

cli/src/main/java/com/devonfw/tools/ide/tool/plugin/ToolPlugins.java

@@ -72,4 +72,27 @@ private void put(String key, ToolPluginDescriptor descriptor, Map<String, ToolPl
       LOG.info("Plugin with key {} was {} but got overridden by {}", key, duplicate, descriptor);
     }
   }
+
+  /**
+   * Activates the plugin with the given {@link ToolPluginDescriptor#name() name} so it will be installed even if it is not
+   * {@link ToolPluginDescriptor#active() active} in its configuration. The descriptor is replaced in all internal indices so that {@link #getPlugins()},
+   * {@link #getByName(String)} and {@link #getById(String)} consistently return the activated variant.
+   *
+   * @param name the {@link ToolPluginDescriptor#name() name} of the plugin to activate.
+   * @return the activated {@link ToolPluginDescriptor} or {@code null} if no plugin with the given {@code name} is configured.
+   */
+  public ToolPluginDescriptor activate(String name) {
+
+    ToolPluginDescriptor descriptor = this.mapByName.get(name);
+    if (descriptor == null) {
+      return null;
+    }
+    ToolPluginDescriptor activated = descriptor.withActive(true);
+    this.mapByName.put(activated.name(), activated);
+    String id = activated.id();
+    if ((id != null) && !id.isEmpty()) {
+      this.mapById.put(id, activated);
+    }
+    return activated;
+  }
 }

cli/src/test/java/com/devonfw/tools/ide/context/AbstractIdeContextTest.java

@@ -32,6 +32,9 @@ public abstract class AbstractIdeContextTest extends Assertions {
   /** {@link #newContext(String) Name of test project} {@value}. */
   protected static final String PROJECT_BASIC = "basic";
 
+  /** {@link #newContext(String) Name of test project} {@value} to test the {@code «TOOL»_PLUGINS_EXTRA} variable. */
+  protected static final String PROJECT_PLUGIN_EXTRA = "plugin-extra";
+
   /** Test- */
   protected static final Path TEST_RESOURCES = Path.of("src/test/resources");
 

cli/src/test/java/com/devonfw/tools/ide/tool/plugin/PluginBasedCommandletTest.java

@@ -3,7 +3,7 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
-
+import java.util.Collection;
 import java.util.List;
 import java.util.Set;
 
@@ -13,8 +13,10 @@
 
 import com.devonfw.tools.ide.common.Tag;
 import com.devonfw.tools.ide.context.AbstractIdeContextTest;
+import com.devonfw.tools.ide.context.IdeContext;
 import com.devonfw.tools.ide.context.IdeTestContext;
 import com.devonfw.tools.ide.context.ProcessContextTestImpl;
+import com.devonfw.tools.ide.environment.EnvironmentVariables;
 
 /**
  * Test of {@link PluginBasedCommandlet}.
@@ -62,17 +64,18 @@ void testGetPluginsMap() {
   void testInstallPluginsWithForce() {
 
     //arrange
-    context.getStartContext().setForcePlugins(true);
-    final ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(context, TOOL, tags);
+    IdeTestContext localContext = newContext(PROJECT_BASIC, null, false);
+    localContext.getStartContext().setForcePlugins(true);
+    final ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(localContext, TOOL, tags);
 
     //act
     pluginBasedCommandlet.installPlugins(
-        List.of(ToolPluginDescriptor.of(context.getSettingsPath().resolve(ANY_EDIT_PLUGIN_PATH), context, false)),
-        new ProcessContextTestImpl(context));
+        List.of(ToolPluginDescriptor.of(localContext.getSettingsPath().resolve(ANY_EDIT_PLUGIN_PATH), localContext, false)),
+        new ProcessContextTestImpl(localContext));
 
     //assert - Check if we skip the markerfile-check because we force the plugins to install
-    assertThat(context).logAtSuccess().hasMessage("Successfully ended step 'Install plugin anyedit (1/1)'.");
-    assertThat(context).log().hasNoMessageContaining("Skipping installation of plugin '{}' due to existing marker file: ");
+    assertThat(localContext).logAtSuccess().hasMessage("Successfully ended step 'Install plugin anyedit (1/1)'.");
+    assertThat(localContext).log().hasNoMessageContaining("Skipping installation of plugin '{}' due to existing marker file: ");
   }
 
   @Test
@@ -119,4 +122,57 @@ void testCreatePluginMarkerFileDeletesOtherVersionMarkers() {
     assertThat(markerBPath).exists();
     assertThat(markerAPath).doesNotExist();
   }
+
+  @Test
+  void testExtraPluginIsActivated() {
+
+    IdeTestContext localContext = newContext(PROJECT_PLUGIN_EXTRA, null, false);
+    ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(localContext, TOOL, tags);
+
+    ToolPluginDescriptor anyedit = pluginBasedCommandlet.getPlugins().getByName("anyedit");
+
+    assertThat(anyedit).isNotNull();
+    assertThat(anyedit.active()).isTrue();
+  }
+
+  @Test
+  void testExtraPluginIsActivatedInPluginCollection() {
+
+    IdeTestContext localContext = newContext(PROJECT_PLUGIN_EXTRA, null, false);
+    ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(localContext, TOOL, tags);
+
+    Collection<ToolPluginDescriptor> plugins = pluginBasedCommandlet.getPlugins().getPlugins();
+
+    assertThat(plugins).filteredOn(plugin -> "anyedit".equals(plugin.name()))
+        .singleElement().extracting(ToolPluginDescriptor::active).isEqualTo(Boolean.TRUE);
+  }
+
+  @Test
+  void testUnlistedPluginKeepsConfiguredState() {
+
+    IdeTestContext localContext = newContext(PROJECT_PLUGIN_EXTRA, null, false);
+    ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(localContext, TOOL, tags);
+
+    ToolPlugins toolPlugins = pluginBasedCommandlet.getPlugins();
+
+    // configured as inactive and not listed in ECLIPSE_PLUGINS_EXTRA - has to stay inactive
+    assertThat(toolPlugins.getByName("checkstyle").active()).isFalse();
+    // configured as active and not listed in ECLIPSE_PLUGINS_EXTRA - has to stay active
+    assertThat(toolPlugins.getByName("spotbugs").active()).isTrue();
+  }
+
+  @Test
+  void testUnknownExtraPluginLogsWarning() throws IOException {
+
+    IdeTestContext localContext = newContext(PROJECT_PLUGIN_EXTRA, null, true);
+    Files.writeString(localContext.getIdeHome().resolve(IdeContext.FOLDER_CONF).resolve(EnvironmentVariables.DEFAULT_PROPERTIES),
+        "ECLIPSE_PLUGINS_EXTRA=anyedit,doesnotexist\n");
+    localContext.reload();
+    ExamplePluginBasedCommandlet pluginBasedCommandlet = new ExamplePluginBasedCommandlet(localContext, TOOL, tags);
+
+    ToolPlugins toolPlugins = pluginBasedCommandlet.getPlugins();
+
+    assertThat(toolPlugins.getByName("anyedit").active()).isTrue();
+    assertThat(localContext).logAtWarning().hasMessageContaining("doesnotexist");
+  }
 }

cli/src/test/resources/ide-projects/plugin-extra/project/conf/ide.properties

@@ -0,0 +1 @@
+ECLIPSE_PLUGINS_EXTRA=anyedit

cli/src/test/resources/ide-projects/plugin-extra/project/settings/eclipse/plugins/anyedit.properties

@@ -0,0 +1,3 @@
+url=https://raw.githubusercontent.com/iloveeclipse/plugins/latest/
+id=AnyEditTools.feature.group
+active=false

cli/src/test/resources/ide-projects/plugin-extra/project/settings/eclipse/plugins/checkstyle.properties

@@ -0,0 +1,3 @@
+url=https://checkstyle.org/eclipse-cs-update-site/
+id=net.sf.eclipsecs.feature.group
+active=false

cli/src/test/resources/ide-projects/plugin-extra/project/settings/eclipse/plugins/spotbugs.properties

@@ -0,0 +1,3 @@
+url=https://spotbugs.github.io/eclipse/
+id=com.github.spotbugs.plugin.eclipse.feature.group
+active=true

cli/src/test/resources/ide-projects/plugin-extra/project/settings/ide.properties

@@ -0,0 +1 @@
+ECLIPSE_VERSION=2023-03

cli/src/test/resources/ide-projects/plugin-extra/project/workspaces/main/readme

@@ -0,0 +1 @@
+this is the main workspace of plugin-extra

documentation/plugin.adoc

@@ -33,6 +33,28 @@ For `VisualStudio Code`,  this is the extension ID you can directly get from the
 |===
 
 
+== Additional plugins per user
+
+The plugins configured in the project link:settings.adoc[settings] are a shared baseline for the entire team.
+If you want additional plugins only for yourself, you do not need to modify the shared settings.
+Instead set the variable `«TOOL»_PLUGINS_EXTRA` in your user-specific link:conf.adoc[configuration] (`$IDE_HOME/conf/ide.properties` or `~/.ide/ide.properties`):
+
+```
+VSCODE_PLUGINS_EXTRA=copilot,cpp-tools,docker
+```
+
+Each entry refers to the filename of the plugin properties file without the `.properties` extension.
+Therefore `copilot` refers to `copilot.properties` and not to the `id` configured inside that file.
+The according plugin still has to be configured as properties file (either in the project settings or in `~/.ide/settings/«ide»/plugins`).
+Entries that cannot be resolved are skipped with a warning so a single stale entry will never break the installation of your other plugins.
+
+This works for every IDE, e.g. `ECLIPSE_PLUGINS_EXTRA`, `INTELLIJ_PLUGINS_EXTRA` or `ANDROID_STUDIO_PLUGINS_EXTRA`.
+
+The benefit over installing a plugin manually inside your IDE is that plugins configured this way are reinstalled automatically whenever IDEasy purges and reinstalls the plugins (e.g. when the IDE is upgraded), whereas manually installed plugins would be lost.
+
+Please note that removing an entry from `«TOOL»_PLUGINS_EXTRA` will not uninstall the according plugin.
+See the next section for how to reset your plugins.
+
 == Resetting installed plugins
 
 When first installing an IDE using `ide install «ide»`, IDEasy will automatically install all plugins that are configured in the project settings.

documentation/variables.adoc

@@ -25,6 +25,7 @@ See also link:https://github.com/devonfw/IDEasy/blob/main/cli/src/main/java/com/
 |`WORKSPACE_PATH`|`$IDE_HOME/workspaces/$WORKSPACE`|Absolute path to current link:workspaces.adoc[workspace]. Never set this variable in any `ide.properties` file.
 |`«TOOL»_VERSION`|`*`|The version of the tool `«TOOL»` to install and use (e.g. `ECLIPSE_VERSION` or `MVN_VERSION`).
 |`«TOOL»_EDITION`|`«tool»`|The edition of the tool `«TOOL»` to install and use (e.g. `ECLIPSE_EDITION`, `INTELLIJ_EDITION` or `DOCKER_EDITION`). Default of `DOCKER_EDITION` is `rancher`.
+|`«TOOL»_PLUGINS_EXTRA`|e.g. `copilot,docker`|Additional link:plugin.adoc[plugins] to install for the IDE `«TOOL»` (e.g. `VSCODE_PLUGINS_EXTRA`, `INTELLIJ_PLUGINS_EXTRA` or `ECLIPSE_PLUGINS_EXTRA`). Each entry refers to the filename of the plugin properties file without the `.properties` extension (e.g. `copilot` for `copilot.properties`) and not to the `id` configured inside that file. This option should only be set for individual users in `$IDE_HOME/conf/ide.properties` or `~/.ide/ide.properties` (and not in shared `settings`).
 |*`«TOOL»_HOME`*|`$IDE_HOME/software/«tool»`|Path to installation of «tool» (e.g. MVN_HOME for maven)
 |`«TOOL»_BUILD_OPTS`|`clean install`|The arguments provided to the build-tool `«TOOL»` in order to run a build. E.g.`clean install`
 |`«TOOL»_RELEASE_OPTS`|e.g. `clean deploy -Dchangelist= -Pdeploy`|The arguments provided to the build-tool `«TOOL»` in order to perform a release build. E.g.`clean deploy -Dchangelist= -Pdeploy`