Add support to group commands at class level

Resolves #1266

Author: fmbenhassine

spring-shell-core/src/main/java/org/springframework/shell/core/command/annotation/CommandGroup.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.core.command.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.aot.hint.annotation.Reflective;
+import org.springframework.stereotype.Component;
+
+/**
+ * Annotation marking a class as a command group. Command groups are used to group related
+ * commands together and provide a common name and prefix for the group.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 4.0.2
+ */
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+@Documented
+@Reflective
+@Component
+public @interface CommandGroup {
+
+	/**
+	 * The name of the command group.
+	 * @return the name of the command group
+	 */
+	String name() default "";
+
+	/**
+	 * The description of the command group.
+	 * @return the description of the command group
+	 */
+	String description() default "";
+
+	/**
+	 * The prefix of the command group.
+	 * @return the prefix of the command group
+	 */
+	String prefix() default "";
+
+}

spring-shell-core/src/main/java/org/springframework/shell/core/command/annotation/support/CommandFactoryBean.java

@@ -39,6 +39,7 @@
 import org.springframework.shell.core.command.CommandCreationException;
 import org.springframework.shell.core.command.CommandOption;
 import org.springframework.shell.core.command.adapter.MethodInvokerCommandAdapter;
+import org.springframework.shell.core.command.annotation.CommandGroup;
 import org.springframework.shell.core.command.annotation.Option;
 import org.springframework.shell.core.command.availability.AvailabilityProvider;
 import org.springframework.shell.core.command.completion.DefaultCompletionProvider;
@@ -75,15 +76,24 @@ public Command getObject() {
 			.get(org.springframework.shell.core.command.annotation.Command.class)
 			.synthesize();
 
+		Class<?> declaringClass = this.method.getDeclaringClass();
+		String groupName = "";
+		String groupPrefix = "";
+		if (declaringClass.isAnnotationPresent(CommandGroup.class)) {
+			CommandGroup commandGroup = MergedAnnotations.from(declaringClass).get(CommandGroup.class).synthesize();
+			groupName = commandGroup.name();
+			groupPrefix = commandGroup.prefix();
+		}
+
 		// get command metadata
-		String name = String.join(" ", command.name());
+		String name = groupPrefix + (groupPrefix.isEmpty() ? "" : " ") + String.join(" ", command.name());
 		name = name.isEmpty() ? Utils.unCamelify(this.method.getName()) : name;
 		String description = command.description();
 		description = description.isEmpty() ? "N/A" : description;
 		String help = command.help();
-		String group = command.group();
+		String group = !command.group().isEmpty() ? command.group() : groupName;
 		if (group.isEmpty()) {
-			String simpleName = Utils.splitCamelCase(this.method.getDeclaringClass().getSimpleName());
+			String simpleName = Utils.splitCamelCase(declaringClass.getSimpleName());
 			if (!simpleName.endsWith(" Commands")) {
 				group = simpleName + " Commands";
 			}
@@ -97,7 +107,6 @@ public Command getObject() {
 		String availabilityProviderBeanName = command.availabilityProvider();
 		String exitStatusExceptionMapperBeanName = command.exitStatusExceptionMapper();
 		String completionProviderBeanName = command.completionProvider();
-		Class<?> declaringClass = this.method.getDeclaringClass();
 		log.debug("Creating command bean for method '%s' defined in class '%s' with name '%s'"
 			.formatted(this.method.getName(), declaringClass.getName(), name));
 		Object targetObject = getTagetObject(declaringClass);

spring-shell-core/src/test/java/org/springframework/shell/core/command/annotation/support/CommandFactoryBeanTests.java

@@ -15,12 +15,15 @@
  */
 package org.springframework.shell.core.command.annotation.support;
 
+import java.lang.reflect.Method;
+import java.util.Arrays;
 import java.util.List;
 
 import org.junit.jupiter.api.Test;
 import org.springframework.context.ApplicationContext;
 import org.springframework.shell.core.command.CommandOption;
 import org.springframework.shell.core.command.annotation.Command;
+import org.springframework.shell.core.command.annotation.CommandGroup;
 import org.springframework.shell.core.command.annotation.Option;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -61,6 +64,48 @@ void testOptionNames() {
 		assertEquals(' ', options.get(3).shortName());
 	}
 
+	@Test
+	public void testCommandGroup() {
+		// given
+		ApplicationContext context = mock(ApplicationContext.class);
+		when(context.getBean(GreetingCommands.class)).thenReturn(new GreetingCommands());
+		Method[] declaredMethods = GreetingCommands.class.getDeclaredMethods();
+		Method hiMethod = Arrays.stream(declaredMethods)
+			.filter(m -> m.getName().equals("hi"))
+			.findFirst()
+			.orElseThrow();
+		CommandFactoryBean commandFactoryBean = new CommandFactoryBean(hiMethod);
+		commandFactoryBean.setApplicationContext(context);
+
+		// when
+		org.springframework.shell.core.command.Command result = commandFactoryBean.getObject();
+
+		// then
+		assertEquals("greeting hi", result.getName());
+		assertEquals("Greeting Commands", result.getGroup());
+	}
+
+	@Test
+	public void testCommandGroupOverride() {
+		// given
+		ApplicationContext context = mock(ApplicationContext.class);
+		when(context.getBean(GreetingCommands.class)).thenReturn(new GreetingCommands());
+		Method[] declaredMethods = GreetingCommands.class.getDeclaredMethods();
+		Method byeMethod = Arrays.stream(declaredMethods)
+			.filter(m -> m.getName().equals("bye"))
+			.findFirst()
+			.orElseThrow();
+		CommandFactoryBean commandFactoryBean = new CommandFactoryBean(byeMethod);
+		commandFactoryBean.setApplicationContext(context);
+
+		// when
+		org.springframework.shell.core.command.Command result = commandFactoryBean.getObject();
+
+		// then
+		assertEquals("greeting bye", result.getName());
+		assertEquals("Farewell Commands", result.getGroup());
+	}
+
 	static class TestClass {
 
 		@Command(name = "hello")
@@ -72,4 +117,19 @@ public void helloMethod(@Option String myOption1, @Option(shortName = 'm') Strin
 
 	}
 
+	@CommandGroup(name = "Greeting Commands", prefix = "greeting")
+	static class GreetingCommands {
+
+		@Command(name = "hi")
+		public void hi() {
+			// no-op
+		}
+
+		@Command(name = "bye", group = "Farewell Commands")
+		public void bye() {
+			// no-op
+		}
+
+	}
+
 }

spring-shell-docs/modules/ROOT/pages/commands/organize.adoc

@@ -35,3 +35,33 @@ Command myCommand() {
             });
 }
 ----
+
+Typically, related commands are defined in the same class (to easily share state between commands), and the group name and prefix are specified at the class level,
+which means that all commands defined in that class will belong to the same group. Here is an example of how to do that:
+
+[source,java]
+----
+@CommandGroup(name = "Authentication Commands", prefix = "auth")
+public class AuthenticationCommands {
+
+	private boolean authenticated = false;
+
+	@Command(name = "login", description = "Log in to the system")
+	public void login() {
+        // Authentication logic here
+        authenticated = true;
+        System.out.println("Logged in successfully!");
+    }
+
+    @Command(name = "logout", description = "Log out of the system")
+    public void logout() {
+        // Logout logic here
+        authenticated = false;
+        System.out.println("Logged out successfully!");
+    }
+}
+----
+
+In this example, both the `login` and `logout` commands belong to the `Authentication Commands` group, and they will be displayed together in the help screen under that group. The `prefix` attribute specifies a common prefix for all commands in that group, which can be used to invoke the commands (e.g., `auth login` and `auth logout`).
+
+NOTE: If a command provides a `group` attribute, it will take precedence over the group specified at the class level. This allows you to override the group for specific commands if needed.

spring-shell-samples/spring-shell-sample-petclinic/src/main/java/org/springframework/shell/samples/petclinic/commands/PetCommands.java

@@ -25,11 +25,11 @@
 import org.springframework.jdbc.core.simple.JdbcClient;
 import org.springframework.shell.core.command.CommandContext;
 import org.springframework.shell.core.command.annotation.Command;
+import org.springframework.shell.core.command.annotation.CommandGroup;
 import org.springframework.shell.core.command.annotation.Option;
 import org.springframework.shell.samples.petclinic.domain.Pet;
-import org.springframework.stereotype.Component;
 
-@Component
+@CommandGroup(name = "Pets commands", description = "Commands to manage pets", prefix = "pets")
 public class PetCommands {
 
 	private final JdbcClient jdbcClient;
@@ -38,8 +38,7 @@ public PetCommands(JdbcClient jdbcClient) {
 		this.jdbcClient = jdbcClient;
 	}
 
-	@Command(name = { "pets", "list" }, description = "List pets", group = "Pets",
-			help = "List pets in Pet Clinic. Usage: pets list")
+	@Command(name = { "list" }, description = "List pets", help = "List pets in Pet Clinic. Usage: pets list")
 	public void listPets(CommandContext commandContext) {
 		List<@Nullable Pet> pets = jdbcClient.sql("SELECT id, name FROM PETS")
 			.query(new DataClassRowMapper<>(Pet.class))
@@ -51,7 +50,7 @@ public void listPets(CommandContext commandContext) {
 		writer.flush();
 	}
 
-	@Command(name = { "pets", "info" }, description = "Show detail about a given pet", group = "Pets",
+	@Command(name = { "info" }, description = "Show detail about a given pet",
 			help = "Show the details about a given pet. Usage: pets info --petId=<id>")
 	public void showPet(@Option(longName = "petId", description = "The pet ID", required = true) int id,
 			CommandContext commandContext) {

spring-shell-samples/spring-shell-sample-secure-input/README.md

@@ -18,4 +18,11 @@ To run the application, use the following command:
 java -jar spring-shell-samples/spring-shell-sample-secure-input/target/secure-input.jar
 ```
 
-You should see a prompt where you can use the `change-password` command to securely input and change a password.
+You should see a prompt where you can login with `auth login`. This command will ask you to enter a username and password securely.
+
+The sample application uses an in-memory user store with a single user `foo` with the password `bar`. You can use these credentials to log in.
+
+After logging in, you can use the `auth change-password` command to securely change the password.
+
+This sample also shows how to use the `AvailabilityProvider` API to restrict access to certain commands based on the user's authentication status.
+For example, the `auth change-password` command is only available when the user is authenticated.

spring-shell-samples/spring-shell-sample-secure-input/src/main/java/org/springframework/shell/samples/secure/input/AuthenticationCommands.java

@@ -0,0 +1,113 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.samples.secure.input;
+
+import java.io.PrintWriter;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.shell.core.InputReader;
+import org.springframework.shell.core.command.CommandContext;
+import org.springframework.shell.core.command.annotation.Command;
+import org.springframework.shell.core.command.annotation.CommandGroup;
+import org.springframework.shell.core.command.availability.Availability;
+import org.springframework.shell.core.command.availability.AvailabilityProvider;
+
+@CommandGroup(name = "Authentication Commands", description = "Commands related to user authentication",
+		prefix = "auth")
+public class AuthenticationCommands {
+
+	private String username;
+
+	private boolean authenticated = false;
+
+	// In-memory user store for demonstration purposes
+	private Map<String, String> userStore = new HashMap<>() {
+		{
+			put("foo", "bar");
+		}
+	};
+
+	@Command(name = "login", description = "Log in to the system")
+	public void login(CommandContext commandContext) {
+		InputReader inputReader = commandContext.inputReader();
+		PrintWriter outputWriter = commandContext.outputWriter();
+		if (this.authenticated) {
+			outputWriter.println("Already logged in.");
+			return;
+		}
+		try {
+			String username = inputReader.readInput("Username: ");
+			String password = new String(inputReader.readPassword("Password: "));
+			if (userStore.containsKey(username) && userStore.get(username).equals(password)) {
+				outputWriter.println("Login successful.");
+				this.authenticated = true;
+				this.username = username;
+			}
+			else {
+				outputWriter.println("Invalid credentials.");
+			}
+		}
+		catch (Exception e) {
+			outputWriter.println("Failed to login.");
+		}
+	}
+
+	@Command(name = "logout", description = "Log out of the system")
+	public void logout() {
+		if (!this.authenticated) {
+			System.out.println("Not logged in.");
+			return;
+		}
+		System.out.println("Logging out...");
+		this.authenticated = false;
+		this.username = null;
+	}
+
+	@Command(name = "status", description = "Check authentication status")
+	public String status() {
+		return authenticated ? "Logged in as " + this.username : "Not logged in.";
+	}
+
+	@Command(name = "change-password", description = "Change password", availabilityProvider = "authenticationProvider")
+	public void changePassword(CommandContext commandContext) {
+		InputReader inputReader = commandContext.inputReader();
+		PrintWriter outputWriter = commandContext.outputWriter();
+		try {
+			char[] currentPassword = inputReader.readPassword("Enter current password: ");
+			if (!userStore.containsKey(this.username)
+					|| !userStore.get(this.username).equals(new String(currentPassword))) {
+				outputWriter.println("Current password is incorrect.");
+				return;
+			}
+			char[] chars = inputReader.readPassword("Enter new password: ");
+			String newPassword = new String(chars);
+			userStore.put(this.username, newPassword);
+			outputWriter.println("Password successfully updated.");
+		}
+		catch (Exception e) {
+			outputWriter.println("Failed to set password.");
+		}
+	}
+
+	@Bean
+	public AvailabilityProvider authenticationProvider() {
+		return () -> this.authenticated ? Availability.available()
+				: Availability.unavailable("You must be logged in to use this command.");
+	}
+
+}