Add support for command availability

- Simplify the way to configure the availability provider
by using a new attribute in the Command annotation instead
of a separate annotation CommandAvailability
- Make Availability a record
- Add utility methods to create common availability providers
- Add new exit status for unavailable commands
- Remove unused CommandNotCurrentlyAvailableException

Author: fmbenhassine

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

@@ -20,6 +20,9 @@
 import java.util.List;
 import java.util.Objects;
 
+import org.springframework.shell.core.command.availability.Availability;
+import org.springframework.shell.core.command.availability.AvailabilityProvider;
+
 /**
  * Base class helping to build shell commands.
  *
@@ -39,6 +42,8 @@ public abstract class AbstractCommand implements Command {
 
 	private final boolean hidden;
 
+	private AvailabilityProvider availabilityProvider = AvailabilityProvider.alwaysAvailable();
+
 	private List<String> aliases = new ArrayList<>();
 
 	public AbstractCommand(String name, String description) {
@@ -91,8 +96,23 @@ public void setAliases(List<String> aliases) {
 		this.aliases = aliases;
 	}
 
+	@Override
+	public AvailabilityProvider getAvailabilityProvider() {
+		return availabilityProvider;
+	}
+
+	public void setAvailabilityProvider(AvailabilityProvider availabilityProvider) {
+		this.availabilityProvider = availabilityProvider;
+	}
+
 	@Override
 	public ExitStatus execute(CommandContext commandContext) throws Exception {
+		Availability availability = getAvailabilityProvider().get();
+		if (!availability.isAvailable()) {
+			println("Command '" + getName() + "' exists but is not currently available because "
+					+ availability.reason(), commandContext);
+			return ExitStatus.AVAILABILITY_ERROR;
+		}
 		List<CommandOption> options = commandContext.parsedInput().options();
 		if (options.size() == 1 && isHelp(options.get(0))) {
 			println(getHelp(), commandContext);

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

@@ -24,6 +24,7 @@
 
 import org.springframework.shell.core.command.adapter.ConsumerCommandAdapter;
 import org.springframework.shell.core.command.adapter.FunctionCommandAdapter;
+import org.springframework.shell.core.command.availability.AvailabilityProvider;
 import org.springframework.util.Assert;
 
 /**
@@ -82,6 +83,14 @@ default List<String> getAliases() {
 		return Collections.emptyList();
 	}
 
+	/**
+	 * Get the availability provider of the command. Defaults to always available.
+	 * @return the availability provider of the command
+	 */
+	default AvailabilityProvider getAvailabilityProvider() {
+		return AvailabilityProvider.alwaysAvailable();
+	}
+
 	/**
 	 * Execute the command within the given context.
 	 * @param commandContext the context of the command
@@ -116,6 +125,8 @@ final class Builder {
 
 		private boolean hidden = false;
 
+		private AvailabilityProvider availabilityProvider = AvailabilityProvider.alwaysAvailable();
+
 		private List<String> aliases = new ArrayList<>();
 
 		public Builder name(String name) {
@@ -143,6 +154,11 @@ public Builder hidden(boolean hidden) {
 			return this;
 		}
 
+		public Builder availabilityProvider(AvailabilityProvider availabilityProvider) {
+			this.availabilityProvider = availabilityProvider;
+			return this;
+		}
+
 		public Builder aliases(String... aliases) {
 			this.aliases = Arrays.asList(aliases);
 			return this;
@@ -154,6 +170,7 @@ public AbstractCommand execute(Consumer<CommandContext> commandExecutor) {
 			ConsumerCommandAdapter command = new ConsumerCommandAdapter(name, description, group, help, hidden,
 					commandExecutor);
 			command.setAliases(aliases);
+			command.setAvailabilityProvider(availabilityProvider);
 
 			return command;
 		}
@@ -164,6 +181,7 @@ public AbstractCommand execute(Function<CommandContext, String> commandExecutor)
 			FunctionCommandAdapter command = new FunctionCommandAdapter(name, description, group, help, hidden,
 					commandExecutor);
 			command.setAliases(aliases);
+			command.setAvailabilityProvider(availabilityProvider);
 
 			return command;
 		}

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

@@ -30,4 +30,6 @@ public record ExitStatus(int code, String description) {
 
 	public static ExitStatus USAGE_ERROR = new ExitStatus(-2, "USAGE_ERROR");
 
+	public static ExitStatus AVAILABILITY_ERROR = new ExitStatus(-3, "AVAILABILITY_ERROR");
+
 }

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

@@ -87,4 +87,10 @@
 	 */
 	String help() default "";
 
+	/**
+	 * Define availability provider bean name.
+	 * @return the availability provider bean name
+	 */
+	String availabilityProvider() default "";
+
 }

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

@@ -32,6 +32,7 @@
 import org.springframework.shell.core.command.Command;
 import org.springframework.shell.core.command.CommandCreationException;
 import org.springframework.shell.core.command.adapter.MethodInvokerCommandAdapter;
+import org.springframework.shell.core.command.availability.AvailabilityProvider;
 import org.springframework.util.Assert;
 
 /**
@@ -66,6 +67,7 @@ public Command getObject() {
 		String group = command.group();
 		boolean hidden = command.hidden();
 		String[] aliases = command.alias();
+		String availabilityProvider = command.availabilityProvider();
 		log.debug("Creating command bean for method '" + this.method + "' with name '" + name + "'");
 		Class<?> declaringClass = this.method.getDeclaringClass();
 		Object targetObject;
@@ -88,9 +90,21 @@ 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.");
 		}
+		AvailabilityProvider availabilityProviderBean = AvailabilityProvider.alwaysAvailable();
+		if (!availabilityProvider.isEmpty()) {
+			try {
+				availabilityProviderBean = this.applicationContext.getBean(availabilityProvider,
+						AvailabilityProvider.class);
+			}
+			catch (BeansException e) {
+				log.debug("No AvailabilityProvider bean found with name '" + availabilityProvider
+						+ "', using always available provider.");
+			}
+		}
 		MethodInvokerCommandAdapter methodInvokerCommandAdapter = new MethodInvokerCommandAdapter(name, description,
 				group, help, hidden, this.method, targetObject, configurableConversionService);
 		methodInvokerCommandAdapter.setAliases(Arrays.stream(aliases).toList());
+		methodInvokerCommandAdapter.setAvailabilityProvider(availabilityProviderBean);
 		return methodInvokerCommandAdapter;
 	}
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 the original author or authors.
+ * Copyright 2017-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.
@@ -20,19 +20,14 @@
 import org.springframework.util.Assert;
 
 /**
- * Indicates whether or not a command is currently available. When not available, provides
+ * Indicates whether a command is currently available or not. When not available, provides
  * a reason.
  *
  * @author Eric Bottard
  * @author Piotr Olaszewski
+ * @author Mahmoud Ben Hassine
  */
-public class Availability {
-
-	private final @Nullable String reason;
-
-	private Availability(@Nullable String reason) {
-		this.reason = reason;
-	}
+public record Availability(@Nullable String reason) {
 
 	public static Availability available() {
 		return new Availability(null);
@@ -47,8 +42,4 @@ public boolean isAvailable() {
 		return reason == null;
 	}
 
-	public @Nullable String getReason() {
-		return reason;
-	}
-
 }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 the original author or authors.
+ * Copyright 2023-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.
@@ -21,8 +21,17 @@
  * Interface resolving {@link Availability}.
  *
  * @author Janne Valkealahti
+ * @author Mahmoud Ben Hassine
  */
 @FunctionalInterface
 public interface AvailabilityProvider extends Supplier<Availability> {
 
+	static AvailabilityProvider alwaysAvailable() {
+		return of(Availability.available());
+	}
+
+	static AvailabilityProvider of(Availability availability) {
+		return () -> availability;
+	}
+
 }

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

@@ -0,0 +1,65 @@
+/*
+ * 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 java.io.PrintWriter;
+import java.io.StringWriter;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.shell.core.command.availability.Availability;
+import org.springframework.shell.core.command.availability.AvailabilityProvider;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+
+/**
+ * Tests for command availability.
+ *
+ * @author Mahmoud Ben Hassine
+ */
+public class CommandAvailabilityTests {
+
+	@Test
+	public void testCommandAvailability() throws Exception {
+		// given
+		Command command = new AbstractCommand("test", "A test command") {
+
+			@Override
+			public AvailabilityProvider getAvailabilityProvider() {
+				return AvailabilityProvider.of(new Availability("you are not allowed to run this command"));
+			}
+
+			@Override
+			public ExitStatus doExecute(CommandContext commandContext) {
+				return ExitStatus.OK;
+			}
+		};
+		StringWriter stringWriter = new StringWriter();
+		CommandContext commandContext = new CommandContext(mock(ParsedInput.class), mock(CommandRegistry.class),
+				new PrintWriter(stringWriter));
+
+		// when
+		ExitStatus exitStatus = command.execute(commandContext);
+
+		// then
+		assertEquals(ExitStatus.AVAILABILITY_ERROR, exitStatus);
+		assertEquals(
+				"Command 'test' exists but is not currently available because you are not allowed to run this command",
+				stringWriter.toString().trim());
+	}
+
+}