feat: completions

README.md

@@ -8,19 +8,24 @@ Rather, it's a way to use a familiar command framework to quickly & easily creat
 
 Spring Shell uses "options" (what Cloud would call flags) for input, which Cloud does not do.
 We therefore map all arguments to an array of strings, which means that we get access to (nearly) all Cloud features.
-The downside of this approach is that we unfortunately cannot support command completions at the moment.
 
 The example module contains a Spring Boot application with a couple of commands.
 
 ## features
 
 - auto-discovery of `CommandBean` instances as well as `@ScanCommands`-annotated classes
 - support for Spring Shell features such as descriptions and command groups
+
+![descriptions](img/descriptions.png)
+![help](img/help.png)
+
 - configurable by overriding the bean bindings
+- completions!
+
+![completions](img/completions.png)
 
 ## limitations
 
-- no suggestions
 - no intermediate executors (you can do `/cat add` and `/cat remove` but not `/cat`)
 
 ## usage
@@ -93,3 +98,14 @@ public class SomeCommand {
     }
 }
 ```
+
+### completions
+
+Cloud suggestions will be invoked to provide suggestions for your commands.
+You can use normal suggestions, but we also offer `CloudCompletionProposal` which
+allows you to use rich completions:
+```java
+CloudCompletionProposal.of("proposal")
+    .displayName("with a display name")
+    .category("and a category");
+```

cloud-spring/src/main/java/org/incendo/cloud/spring/CloudCompletionProposal.java

@@ -0,0 +1,93 @@
+//
+// MIT License
+//
+// Copyright (c) 2023 Incendo
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+package org.incendo.cloud.spring;
+
+import cloud.commandframework.arguments.suggestion.Suggestion;
+import org.apiguardian.api.API;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.springframework.shell.CompletionProposal;
+
+@API(status = API.Status.STABLE, since = "1.0.0")
+public final class CloudCompletionProposal extends CompletionProposal implements Suggestion {
+
+    /**
+     * Creates a {@link CloudCompletionProposal} from the given {@code suggestion}.
+     *
+     * @param suggestion the suggestion
+     * @return the proposal
+     */
+    public static @NonNull CloudCompletionProposal fromSuggestion(final @NonNull Suggestion suggestion) {
+        if (suggestion instanceof CloudCompletionProposal cloudCompletionProposal) {
+            return cloudCompletionProposal;
+        }
+        return new CloudCompletionProposal(suggestion.suggestion());
+    }
+
+    /**
+     * Returns a {@link CloudCompletionProposal} using the given {@code value}.
+     *
+     * @param value the value
+     * @return the proposal
+     */
+    public static @NonNull CloudCompletionProposal of(final @NonNull String value) {
+        return new CloudCompletionProposal(value);
+    }
+
+    private CloudCompletionProposal(final @NonNull String value) {
+        super(value);
+        this.dontQuote(true);
+        this.complete(false);
+    }
+
+    @Override
+    public @NonNull String suggestion() {
+        return this.value();
+    }
+
+    @Override
+    public @NonNull CloudCompletionProposal value(final @NonNull String value) {
+        return (CloudCompletionProposal) super.value(value);
+    }
+
+    @Override
+    public @NonNull CloudCompletionProposal displayText(final @Nullable String displayText) {
+        return (CloudCompletionProposal) super.displayText(displayText);
+    }
+
+    @Override
+    public @NonNull CloudCompletionProposal category(final @Nullable String category) {
+        return (CloudCompletionProposal) super.category(category);
+    }
+
+    @Override
+    public @NonNull CloudCompletionProposal dontQuote(final boolean dontQuote) {
+        return (CloudCompletionProposal) super.dontQuote(dontQuote);
+    }
+
+    @Override
+    public @NonNull CloudCompletionProposal withSuggestion(final @NonNull String suggestion) {
+        return this.value(suggestion);
+    }
+}

cloud-spring/src/main/java/org/incendo/cloud/spring/SpringCommandManager.java

@@ -24,25 +24,31 @@
 package org.incendo.cloud.spring;
 
 import cloud.commandframework.CommandManager;
+import cloud.commandframework.arguments.suggestion.SuggestionFactory;
 import cloud.commandframework.context.CommandInput;
 import cloud.commandframework.exceptions.ArgumentParseException;
 import cloud.commandframework.exceptions.InvalidCommandSenderException;
 import cloud.commandframework.exceptions.InvalidSyntaxException;
 import cloud.commandframework.exceptions.NoPermissionException;
 import cloud.commandframework.exceptions.NoSuchCommandException;
 import cloud.commandframework.keys.CloudKey;
+import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.List;
 import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.incendo.cloud.spring.event.CommandExecutionEvent;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.context.event.EventListener;
+import org.springframework.shell.CompletionContext;
+import org.springframework.shell.CompletionProposal;
+import org.springframework.shell.completion.CompletionResolver;
 import org.springframework.stereotype.Component;
 
 @Component
 @API(status = API.Status.STABLE, since = "1.0.0")
-public class SpringCommandManager<C> extends CommandManager<C> {
+public class SpringCommandManager<C> extends CommandManager<C> implements CompletionResolver {
 
     public static final CloudKey<String> COMMAND_GROUP_KEY = CloudKey.of("group", String.class);
 
@@ -56,6 +62,7 @@ public class SpringCommandManager<C> extends CommandManager<C> {
 
     private final SpringCommandPermissionHandler<C> commandPermissionHandler;
     private final CommandSenderSupplier<C> commandSenderSupplier;
+    private final SuggestionFactory<C, CloudCompletionProposal> suggestionFactory;
 
     /**
      * Creates a new command manager.
@@ -74,6 +81,7 @@ public SpringCommandManager(
         super(commandExecutionCoordinatorResolver, commandRegistrationHandler);
         this.commandPermissionHandler = commandPermissionHandler;
         this.commandSenderSupplier = commandSenderSupplier;
+        this.suggestionFactory = super.suggestionFactory().mapped(CloudCompletionProposal::fromSuggestion);
 
         this.registerDefaultExceptionHandlers();
     }
@@ -89,6 +97,23 @@ void commandExecutionEvent(final @NonNull CommandExecutionEvent<C> event) {
         this.executeCommand(this.commandSenderSupplier.supply(), commandInput.input());
     }
 
+    @Override
+    public final @NonNull SuggestionFactory<C, ? extends CloudCompletionProposal> suggestionFactory() {
+        return this.suggestionFactory;
+    }
+
+    @Override
+    public final @NonNull List<@NonNull CompletionProposal> apply(final @NonNull CompletionContext completionContext) {
+        final List<String> strings = new ArrayList<>();
+        strings.add(completionContext.getCommandRegistration().getCommand());
+        strings.addAll(completionContext.getWords());
+        final String input = String.join(" ", strings);
+
+        return this.suggestionFactory().suggestImmediately(this.commandSenderSupplier.supply(), input).stream()
+                .map(suggestion -> (CompletionProposal) suggestion)
+                .toList();
+    }
+
     private void registerDefaultExceptionHandlers() {
         this.exceptionController()
                 .registerHandler(Throwable.class, ctx -> LOGGER.error(MESSAGE_INTERNAL_ERROR, ctx.exception()))

example/src/main/java/org/incendo/cloud/spring/example/commands/AddCatCommand.java

@@ -27,9 +27,12 @@
 import cloud.commandframework.CommandBean;
 import cloud.commandframework.CommandProperties;
 import cloud.commandframework.arguments.flags.CommandFlag;
+import cloud.commandframework.arguments.suggestion.SuggestionProvider;
 import cloud.commandframework.context.CommandContext;
 import cloud.commandframework.meta.CommandMeta;
+import java.util.List;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.incendo.cloud.spring.CloudCompletionProposal;
 import org.incendo.cloud.spring.SpringCommandManager;
 import org.incendo.cloud.spring.SpringCommandSender;
 import org.incendo.cloud.spring.example.model.Cat;
@@ -70,7 +73,11 @@ public AddCatCommand(final @NonNull CatService catService) {
     @Override
     protected Command.Builder<SpringCommandSender> configure(final Command.Builder<SpringCommandSender> builder) {
         return builder.literal("add")
-                .required("name", stringParser())
+                .required("name", stringParser(), SuggestionProvider.blocking((ctx, in) -> List.of(
+                        CloudCompletionProposal.of("Missy").displayText("Missy (A cute cat name)"),
+                        CloudCompletionProposal.of("Donald").displayText("Donald (Old man name = CUTE!)"),
+                        CloudCompletionProposal.of("Fluffy").displayText("Fluffy (A classic :))")
+                )))
                 .flag(CommandFlag.builder("override"))
                 .commandDescription(commandDescription("Add a cat"));
     }

example/src/main/java/org/incendo/cloud/spring/example/commands/RemoveCatCommand.java

@@ -26,8 +26,11 @@
 import cloud.commandframework.Command;
 import cloud.commandframework.CommandBean;
 import cloud.commandframework.CommandProperties;
+import cloud.commandframework.arguments.suggestion.Suggestion;
+import cloud.commandframework.arguments.suggestion.SuggestionProvider;
 import cloud.commandframework.context.CommandContext;
 import cloud.commandframework.meta.CommandMeta;
+import java.util.stream.Collectors;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.incendo.cloud.spring.SpringCommandManager;
 import org.incendo.cloud.spring.SpringCommandSender;
@@ -63,7 +66,10 @@ public RemoveCatCommand(final @NonNull CatService catService) {
 
     @Override
     protected Command.Builder<SpringCommandSender> configure(final Command.Builder<SpringCommandSender> builder) {
-        return builder.literal("remove").required("name", stringParser()).commandDescription(commandDescription("Remove a cat"));
+        return builder.literal("remove")
+                .required("name", stringParser(), SuggestionProvider.blocking((ctx, in) ->
+                        this.catService.cats().stream().map(Cat::name).map(Suggestion::simple).collect(Collectors.toList())))
+                .commandDescription(commandDescription("Remove a cat"));
     }
 
     @Override