Add support for hidden commands

Author: fmbenhassine

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

@@ -37,21 +37,24 @@ public abstract class AbstractCommand implements Command {
 
 	private final String group;
 
+	private final boolean hidden;
+
 	private List<String> aliases = new ArrayList<>();
 
 	public AbstractCommand(String name, String description) {
-		this(name, description, "", "");
+		this(name, description, "", "", false);
 	}
 
 	public AbstractCommand(String name, String description, String group) {
-		this(name, description, group, "");
+		this(name, description, group, "", false);
 	}
 
-	public AbstractCommand(String name, String description, String group, String help) {
+	public AbstractCommand(String name, String description, String group, String help, boolean hidden) {
 		this.name = name;
 		this.description = description;
 		this.group = group;
 		this.help = help;
+		this.hidden = hidden;
 	}
 
 	@Override
@@ -74,6 +77,11 @@ public String getHelp() {
 		return this.help;
 	}
 
+	@Override
+	public boolean isHidden() {
+		return this.hidden;
+	}
+
 	@Override
 	public List<String> getAliases() {
 		return this.aliases;

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

@@ -58,6 +58,14 @@ default String getHelp() {
 		return getName() + "(" + String.join(",", getAliases()) + "): " + getDescription();
 	}
 
+	/**
+	 * Check if the command is hidden.
+	 * @return true if the command is hidden, false otherwise
+	 */
+	default boolean isHidden() {
+		return false;
+	}
+
 	/**
 	 * Get the group of the command.
 	 * @return the group of the command
@@ -106,6 +114,8 @@ final class Builder {
 
 		private String help = "";
 
+		private boolean hidden = false;
+
 		private List<String> aliases = new ArrayList<>();
 
 		public Builder name(String name) {
@@ -128,6 +138,11 @@ public Builder group(String group) {
 			return this;
 		}
 
+		public Builder hidden(boolean hidden) {
+			this.hidden = hidden;
+			return this;
+		}
+
 		public Builder aliases(String... aliases) {
 			this.aliases = Arrays.asList(aliases);
 			return this;
@@ -136,7 +151,7 @@ public Builder aliases(String... aliases) {
 		public AbstractCommand execute(Consumer<CommandContext> commandExecutor) {
 			Assert.hasText(name, "'name' must be specified");
 
-			ConsumerCommandAdapter command = new ConsumerCommandAdapter(name, description, group, help,
+			ConsumerCommandAdapter command = new ConsumerCommandAdapter(name, description, group, help, hidden,
 					commandExecutor);
 
 			initAliases(command);
@@ -147,7 +162,7 @@ public AbstractCommand execute(Consumer<CommandContext> commandExecutor) {
 		public AbstractCommand execute(Function<CommandContext, String> commandExecutor) {
 			Assert.hasText(name, "'name' must be specified");
 
-			FunctionCommandAdapter command = new FunctionCommandAdapter(name, description, group, help,
+			FunctionCommandAdapter command = new FunctionCommandAdapter(name, description, group, help, hidden,
 					commandExecutor);
 
 			initAliases(command);

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

@@ -58,11 +58,18 @@ public Set<Command> getCommands() {
 	}
 
 	@Nullable public Command getCommandByName(String name) {
-		return commands.stream().filter(command -> command.getName().equals(name)).findFirst().orElse(null);
+		return commands.stream()
+			.filter(command -> !command.isHidden())
+			.filter(command -> command.getName().equals(name))
+			.findFirst()
+			.orElse(null);
 	}
 
 	public List<Command> getCommandsByPrefix(String prefix) {
-		return commands.stream().filter(command -> command.getName().startsWith(prefix)).toList();
+		return commands.stream()
+			.filter(command -> !command.isHidden())
+			.filter(command -> command.getName().startsWith(prefix))
+			.toList();
 	}
 
 	public void registerCommand(Command command) {

spring-shell-core/src/main/java/org/springframework/shell/core/command/adapter/ConsumerCommandAdapter.java

@@ -37,11 +37,12 @@ public class ConsumerCommandAdapter extends AbstractCommand {
 	 * @param description the description of the command
 	 * @param group the group of the command
 	 * @param help the help text of the command
+	 * @param hidden whether the command is hidden or not
 	 * @param commandExecutor the consumer to adapt as a command
 	 */
-	public ConsumerCommandAdapter(String name, String description, String group, String help,
+	public ConsumerCommandAdapter(String name, String description, String group, String help, boolean hidden,
 			Consumer<CommandContext> commandExecutor) {
-		super(name, description, group, help);
+		super(name, description, group, help, hidden);
 		this.commandExecutor = commandExecutor;
 	}
 

spring-shell-core/src/main/java/org/springframework/shell/core/command/adapter/FunctionCommandAdapter.java

@@ -39,11 +39,12 @@ public class FunctionCommandAdapter extends AbstractCommand {
 	 * @param description the description of the command
 	 * @param group the group of the command
 	 * @param help the help text of the command
+	 * @param hidden whether the command is hidden or not
 	 * @param commandFunction the function to adapt as a command
 	 */
-	public FunctionCommandAdapter(String name, String description, String group, String help,
+	public FunctionCommandAdapter(String name, String description, String group, String help, boolean hidden,
 			Function<CommandContext, String> commandFunction) {
-		super(name, description, group, help);
+		super(name, description, group, help, hidden);
 		this.commandFunction = commandFunction;
 	}
 

spring-shell-core/src/main/java/org/springframework/shell/core/command/adapter/MethodInvokerCommandAdapter.java

@@ -55,13 +55,14 @@ public class MethodInvokerCommandAdapter extends AbstractCommand {
 	 * @param description the description of the command
 	 * @param group the group of the command
 	 * @param help the help text of the command
+	 * @param hidden whether the command is hidden or not
 	 * @param method the method to invoke
 	 * @param targetObject the target object on which to invoke the method
 	 * @param conversionService the conversion service to use for parameter conversion
 	 */
-	public MethodInvokerCommandAdapter(String name, String description, String group, String help, Method method,
-			Object targetObject, ConfigurableConversionService conversionService) {
-		super(name, description, group, help);
+	public MethodInvokerCommandAdapter(String name, String description, String group, String help, boolean hidden,
+			Method method, Object targetObject, ConfigurableConversionService conversionService) {
+		super(name, description, group, help, hidden);
 		this.method = method;
 		this.targetObject = targetObject;
 		this.conversionService = conversionService;

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

@@ -59,11 +59,12 @@ public Command getObject() {
 		org.springframework.shell.core.command.annotation.Command command = MergedAnnotations.from(this.method)
 			.get(org.springframework.shell.core.command.annotation.Command.class)
 			.synthesize();
-		// TODO handle aliases, hidden flag.
+		// TODO handle aliases
 		String name = String.join(" ", command.name());
 		String description = command.description();
 		String help = command.help();
 		String group = command.group();
+		boolean hidden = command.hidden();
 		log.debug("Creating command bean for method '" + this.method + "' with name '" + name + "'");
 		Class<?> declaringClass = this.method.getDeclaringClass();
 		Object targetObject;
@@ -86,7 +87,7 @@ Ensure that the declaring class is annotated with a Spring stereotype annotation
 		catch (BeansException e) {
 			log.debug("No ConfigurableConversionService bean found, using a default conversion service.");
 		}
-		return new MethodInvokerCommandAdapter(name, description, group, help, this.method, targetObject,
+		return new MethodInvokerCommandAdapter(name, description, group, help, hidden, this.method, targetObject,
 				configurableConversionService);
 	}
 

spring-shell-core/src/main/java/org/springframework/shell/core/utils/CommandUtils.java

@@ -42,7 +42,7 @@ public class CommandUtils {
 	}
 
 	/**
-	 * Get a formatted string of available commands from the command registry.
+	 * Get a formatted string of available non-hidden commands from the command registry.
 	 * @param commandRegistry the command registry
 	 * @return a string of available commands with their descriptions
 	 */
@@ -51,6 +51,7 @@ public static String formatAvailableCommands(CommandRegistry commandRegistry) {
 		stringBuilder.append(System.lineSeparator());
 		List<String> groups = commandRegistry.getCommands()
 			.stream()
+			.filter(command -> !command.isHidden())
 			.map(Command::getGroup)
 			.distinct()
 			.sorted()

spring-shell-core/src/test/java/org/springframework/shell/core/command/CommandRegistryTests.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2025-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;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class CommandRegistryTests {
+
+	private final CommandRegistry commandRegistry = new CommandRegistry();
+
+	@Test
+	void getCommandByName() {
+		// given
+		commandRegistry.registerCommand(new Command() {
+
+			@Override
+			public String getName() {
+				return "cmd1";
+			}
+
+			@Override
+			public ExitStatus execute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		});
+		commandRegistry.registerCommand(new Command() {
+
+			@Override
+			public String getName() {
+				return "cmd2";
+			}
+
+			@Override
+			public boolean isHidden() {
+				return true;
+			}
+
+			@Override
+			public ExitStatus execute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		});
+
+		// when
+		Command cmd1 = commandRegistry.getCommandByName("cmd1");
+		Command cmd2 = commandRegistry.getCommandByName("cmd2");
+		Command cmd3 = commandRegistry.getCommandByName("cmd3");
+
+		// then
+		assertNotNull(cmd1);
+		assertNull(cmd2); // hidden command should not be returned
+		assertNull(cmd3); // non-existing command should return null
+	}
+
+	@Test
+	void getCommandsByPrefix() {
+		// given
+		commandRegistry.registerCommand(new Command() {
+
+			@Override
+			public String getName() {
+				return "start";
+			}
+
+			@Override
+			public ExitStatus execute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		});
+		commandRegistry.registerCommand(new Command() {
+
+			@Override
+			public String getName() {
+				return "status";
+			}
+
+			@Override
+			public ExitStatus execute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		});
+		commandRegistry.registerCommand(new Command() {
+
+			@Override
+			public String getName() {
+				return "stop";
+			}
+
+			@Override
+			public boolean isHidden() {
+				return true;
+			}
+
+			@Override
+			public ExitStatus execute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		});
+
+		// when
+		var commands = commandRegistry.getCommandsByPrefix("st");
+
+		// then
+		assertEquals(2, commands.size());
+		assertTrue(commands.stream().anyMatch(cmd -> cmd.getName().equals("start")));
+		assertTrue(commands.stream().anyMatch(cmd -> cmd.getName().equals("status")));
+	}
+
+}

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

@@ -36,7 +36,7 @@ public class OwnerDetailsCommand extends AbstractCommand {
 	private final JdbcClient jdbcClient;
 
 	public OwnerDetailsCommand(JdbcClient jdbcClient) {
-		super("owners info", "Show details of a given owner", "Owners", "show the details of a given owner");
+		super("owners info", "Show details of a given owner", "Owners", "show the details of a given owner", false);
 		this.jdbcClient = jdbcClient;
 	}