#1392: Smart completions

CHANGELOG.adoc

@@ -31,6 +31,7 @@ Release with new features and bugfixes:
 * https://github.com/devonfw/IDEasy/issues/800[#800]: Fix infinite recursion in Sonar start/stop on macOS
 * https://github.com/devonfw/IDEasy/issues/1716[#1716]: Add commandlet for Claude Code CLI
 * https://github.com/devonfw/IDEasy/issues/1844[#1844]: Fix vscode installation hanging indefinitely in WSL Linux environments
+* https://github.com/devonfw/IDEasy/issues/1392[#1392]: Smart completions
 
 The full list of changes for this release can be found in https://github.com/devonfw/IDEasy/milestone/44?closed=1[milestone 2026.05.001].
 

cli/src/main/java/com/devonfw/tools/ide/cli/CliArgument.java

@@ -273,6 +273,19 @@ public String toString() {
     return this.arg;
   }
 
+  public static CliArgument of(int completionIdx, String... args) {
+    CliArgument current = END;
+    int last = args.length - 1;
+
+    for (int argsIdx = last; argsIdx >= 0; argsIdx--) {
+      String arg = args[argsIdx];
+      boolean completionArg = argsIdx == completionIdx;
+
+      current = new CliArgument(arg, current, completionArg);
+    }
+
+    return current.createStart();
+  }
   /**
    * @param args the command-line arguments (e.g. from {@code main} method).
    * @return the first {@link CliArgument} of the parsed arguments or {@code null} if for empty arguments.

cli/src/main/java/com/devonfw/tools/ide/cli/CliArguments.java

@@ -15,6 +15,10 @@ public class CliArguments implements Iterator<CliArgument> {
 
   private boolean splitShortOpts;
 
+  public CliArguments(int completionIdx, String... args) {
+    this(CliArgument.of(completionIdx, args));
+  }
+
   /**
    * The constructor.
    *
@@ -165,6 +169,10 @@ public String toString() {
     return this.currentArg.getArgs();
   }
 
+  public static CliArguments of(int completionIdx, String... args) {
+    return new CliArguments(completionIdx, args);
+  }
+
   /**
    * @param args the {@link CliArgument#of(String...) command line arguments}.
    * @return the {@link CliArguments}.

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

@@ -98,6 +98,28 @@ protected void addKeyword(String keyword) {
     addKeyword(keyword, null);
   }
 
+  /**
+   * Create a new keyword property and set it as the first keyword property.
+   *
+   * @param keyword the string to create the property from
+   * @param alias the alias for the given keyword
+   */
+  protected void setFirstKeyword(String keyword, String alias) {
+    KeywordProperty property = new KeywordProperty(keyword, true, alias);
+
+    this.firstKeyword = property;
+    this.add(property);
+  }
+
+  /**
+   * Create a new keyword property without an alias and set it as the first keyword property.
+   *
+   * @param keyword the string to create the property from
+   */
+  protected void setFirstKeyword(String keyword) {
+    this.setFirstKeyword(keyword, null);
+  }
+
   /**
    * @param keyword the {@link KeywordProperty keyword} to {@link #add(Property) add}.
    * @param alias the optional {@link KeywordProperty#getAlias() alias}.
@@ -191,7 +213,7 @@ public boolean isIdeHomeRequired() {
    */
   public boolean isIdeRootRequired() {
 
-    return true;
+    return !this.context.isTest();
   }
 
   /**

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

@@ -95,6 +95,15 @@ default LocalToolCommandlet getRequiredLocalToolCommandlet(String name) {
     throw new IllegalArgumentException("The commandlet " + name + " is not a LocalToolCommandlet!");
   }
 
+  /**
+   *  Gather all completion candidates.
+   *
+   *  @param arguments the arguments to complete
+   *  @param collector the collector to store completions
+   */
+  public abstract void collectCompletionCandidates(CliArguments arguments,
+      CompletionCandidateCollector collector);
+
   /**
    * @param arguments the {@link CliArguments}.
    * @param collector the optional {@link CompletionCandidateCollector}. Will be {@code null} if no argument {@link CliArguments#isCompletion() completion}

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

@@ -174,10 +174,7 @@ protected void add(Commandlet commandlet) {
     if (keyword != null) {
       String name = keyword.getName();
       registerKeyword(name, commandlet);
-      String optionName = keyword.getOptionName();
-      if (!optionName.equals(name)) {
-        registerKeyword(optionName, commandlet);
-      }
+
       String alias = keyword.getAlias();
       if (alias != null) {
         registerKeyword(alias, commandlet);
@@ -236,10 +233,36 @@ public Commandlet getCommandletByFirstKeyword(String keyword) {
     return this.firstKeywordMap.get(keyword);
   }
 
+  @Override
+  public void collectCompletionCandidates(CliArguments arguments,
+                                          CompletionCandidateCollector collector) {
+    CliArgument current = arguments.current();
+    if (current.isStart()) {
+      arguments.next();
+      current = arguments.current();
+    }
+    if (current.isEnd()) {
+      return;
+    }
+
+    for (Commandlet cmd : this.getCommandlets()) {
+      if (this.context.isTest() || !cmd.isIdeHomeRequired() || this.context.getIdeHome() != null) {
+        KeywordProperty firstKeyword = cmd.getFirstKeyword();
+        if (firstKeyword != null && !firstKeyword.isPlaceholder()) {
+          firstKeyword.apply(arguments, this.context, cmd, collector);
+        }
+      }
+    }
+  }
+
   @Override
   public Iterator<Commandlet> findCommandlet(CliArguments arguments, CompletionCandidateCollector collector) {
 
     CliArgument current = arguments.current();
+    if (current.isStart()) {
+      arguments.next();
+      current = arguments.current();
+    }
     if (current.isEnd()) {
       return Collections.emptyIterator();
     }

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

@@ -36,7 +36,7 @@ public HelpCommandlet(IdeContext context) {
 
     super(context);
     addKeyword("--help", "-h");
-    this.commandlet = add(new CommandletProperty("", false, "commandlet"));
+    this.commandlet = add(new CommandletProperty("", false, "commandlet", false));
   }
 
   @Override

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

@@ -68,13 +68,13 @@ public boolean isIdeHomeRequired() {
 
   @Override
   protected void doRun() {
+    this.setFirstKeyword("exit");
 
     try {
       Parser parser = new DefaultParser();
       try (Terminal terminal = TerminalBuilder.builder().build()) {
         // initialize our own completer here and add exit as an autocompletion option
-        Completer completer = new AggregateCompleter(
-            new StringsCompleter("exit"), new IdeCompleter((AbstractIdeContext) this.context));
+        Completer completer = new IdeCompleter((AbstractIdeContext) this.context);
 
         LineReader reader = LineReaderBuilder.builder().terminal(terminal).completer(completer).parser(parser)
             .variable(LineReader.LIST_MAX, AUTOCOMPLETER_MAX_RESULTS).build();

cli/src/main/java/com/devonfw/tools/ide/completion/CompletionCandidate.java

@@ -1,16 +1,24 @@
 package com.devonfw.tools.ide.completion;
 
+import java.util.List;
+
 /**
  * Candidate for auto-completion.
  *
  * @param text the text to suggest (CLI argument value).
  * @param description the description of the candidate.
  */
-public record CompletionCandidate(String text, String description) implements Comparable<CompletionCandidate> {
+public record CompletionCandidate(List<String> entries,
+                                  String description,
+                                  boolean complete) implements Comparable<CompletionCandidate> {
 
   @Override
   public int compareTo(CompletionCandidate o) {
 
-    return this.text.compareTo(o.text);
+    return this.text().compareTo(o.text());
+  }
+
+  public String text() {
+    return String.join(" ", this.entries);
   }
 }

cli/src/main/java/com/devonfw/tools/ide/completion/CompletionCandidateCollector.java

@@ -12,13 +12,20 @@
  */
 public interface CompletionCandidateCollector {
 
+  /**
+   * Directly add a {@link CompletionCandidate}.
+   *
+   * @param completion the {@link CompletionCandidate} to add
+   */
+  void add(CompletionCandidate completion);
+
   /**
    * @param text the suggested word to add to auto-completion.
    * @param description the description of the suggestion candidate or {@code null} to determine automatically form the given parameters.
    * @param property the {@link Property} that triggered this suggestion.
    * @param commandlet the {@link Commandlet} owning the {@link Property}.
    */
-  void add(String text, String description, Property<?> property, Commandlet commandlet);
+  void add(String text, String description);
 
   /**
    * @param text the suggested word to add to auto-completion.
@@ -27,12 +34,13 @@ public interface CompletionCandidateCollector {
    * @param commandlet the {@link Commandlet} owning the {@link Property}.
    * @return the {@link CompletionCandidate} for the given parameters.
    */
-  default CompletionCandidate createCandidate(String text, String description, Property<?> property, Commandlet commandlet) {
-
+  default CompletionCandidate createCandidate(String text, String description, boolean complete) {
     if (description == null) {
       // compute description from property + commandlet like in HelpCommandlet?
     }
-    CompletionCandidate candidate = new CompletionCandidate(text, description);
+
+    CompletionCandidate candidate = new CompletionCandidate(Arrays.asList(text.split(" ")),
+        description, complete);
     return candidate;
   }
 
@@ -47,7 +55,7 @@ default int addAllMatches(String text, String[] sortedCandidates, Property<?> pr
 
     if (text.isEmpty()) {
       for (String candidate : sortedCandidates) {
-        add(candidate, "", property, commandlet);
+        add(candidate, "");
       }
       return sortedCandidates.length;
     }
@@ -56,7 +64,7 @@ default int addAllMatches(String text, String[] sortedCandidates, Property<?> pr
         .collect(Collectors.toList());
 
     for (String match : prefixWords) {
-      add(match, "", property, commandlet);
+      add(match, "");
     }
 
     return prefixWords.size();

cli/src/main/java/com/devonfw/tools/ide/completion/CompletionCandidateCollectorAdapter.java

@@ -2,9 +2,6 @@
 
 import java.util.List;
 
-import com.devonfw.tools.ide.commandlet.Commandlet;
-import com.devonfw.tools.ide.property.Property;
-
 /**
  * Implementation of {@link CompletionCandidateCollector} that wraps an existing {@link CompletionCandidateCollector} adding a prefix.
  */
@@ -28,9 +25,13 @@ public CompletionCandidateCollectorAdapter(String prefix, CompletionCandidateCol
   }
 
   @Override
-  public void add(String text, String description, Property<?> property, Commandlet commandlet) {
+  public void add(CompletionCandidate completion) {
+    this.delegate.add(this.prefix + completion.text(), completion.description());
+  }
 
-    this.delegate.add(this.prefix + text, description, property, commandlet);
+  @Override
+  public void add(String text, String description) {
+    this.delegate.add(this.prefix + text, description);
   }
 
   @Override

cli/src/main/java/com/devonfw/tools/ide/completion/CompletionCandidateCollectorDefault.java

@@ -38,19 +38,28 @@ public CompletionCandidateCollectorDefault(IdeContext context) {
   }
 
   @Override
-  public void add(String text, String description, Property<?> property, Commandlet commandlet) {
+  public void add(CompletionCandidate completion) {
+    for (CompletionCandidate existing : this.candidates) {
+      if (existing.text().equals(completion.text())) {
+        return;
+      }
+    }
 
-    // Check if this candidate already exists to avoid duplicates
+    this.candidates.add(completion);
+  }
+
+  @Override
+  public void add(String text, String description) {
     for (CompletionCandidate existing : this.candidates) {
       if (existing.text().equals(text)) {
-        // Duplicate candidate found, do not add
         return;
       }
     }
 
-    CompletionCandidate candidate = createCandidate(text, description, property, commandlet);
+    CompletionCandidate candidate = this.createCandidate(text, description, !text.endsWith("="));
     this.candidates.add(candidate);
-    LOG.trace("Added {} for auto-completion of property {}.{}", candidate, commandlet, property);
+
+    LOG.trace("Added {} for auto-completion.", candidate);
   }
 
   @Override
@@ -79,5 +88,4 @@ public String toString() {
 
     return this.candidates.toString();
   }
-
 }

cli/src/main/java/com/devonfw/tools/ide/completion/IdeCompleter.java

@@ -35,7 +35,8 @@ public void complete(LineReader reader, ParsedLine commandLine, List<Candidate>
     List<CompletionCandidate> completion = this.context.complete(args, true);
     int i = 0;
     for (CompletionCandidate candidate : completion) {
-      candidates.add(new Candidate(candidate.text(), candidate.text(), null, null, null, null, true, i++));
+      candidates.add(new Candidate(candidate.text(), candidate.text(), null, null, null, null,
+                                   candidate.complete(), i++));
     }
   }