Improve getting-started and fix API inaccuracies in converters, validators, activators docs

Author: stalep

content/docs/aesh/activators.md

@@ -5,28 +5,41 @@ title: 'Activators'
 weight: 11
 ---
 
-Activators control whether options, arguments, or entire commands are available/enabled.
+Activators control whether options or entire commands are available. Deactivated options are hidden from tab completion and help, and deactivated commands are invisible to the user.
 
 ## OptionActivator
 
-Enable or disable an option based on conditions:
+Enable or disable an option based on conditions. The `ParsedCommand` gives you access to the current command and the values of other options that have been parsed so far:
 
 ```java
+public interface OptionActivator {
+    boolean isActivated(ParsedCommand parsedCommand);
+}
+```
+
+### Example: Conditional Options
+
+SSL-related options should only appear when `--secure` is used:
+
+```java
+import org.aesh.command.activator.OptionActivator;
+import org.aesh.command.impl.internal.ParsedCommand;
+
 public class SslOptionActivator implements OptionActivator {
 
     @Override
-    public boolean isActivated(CompleterInvocation invocation) {
-        MyCommand cmd = (MyCommand) invocation.getCommand();
-        // SSL options only active if secure mode is enabled
-        return cmd.secureMode;
+    public boolean isActivated(ParsedCommand parsedCommand) {
+        // SSL options only active if --secure has been specified
+        return parsedCommand.findLongOptionNoActivatorCheck("secure")
+                .getValue() != null;
     }
 }
 ```
 
 Usage:
 
 ```java
-@CommandDefinition(name = "server")
+@CommandDefinition(name = "server", description = "Start the server")
 public class ServerCommand implements Command<CommandInvocation> {
 
     @Option(name = "secure", hasValue = false, description = "Enable secure mode")
@@ -48,34 +61,43 @@ public class ServerCommand implements Command<CommandInvocation> {
 
     @Override
     public CommandResult execute(CommandInvocation invocation) {
+        if (secureMode) {
+            invocation.println("Starting HTTPS with cert=" + certPath);
+        } else {
+            invocation.println("Starting HTTP server");
+        }
         return CommandResult.SUCCESS;
     }
 }
 ```
 
+When `--secure` is not set, `--cert` and `--key` are hidden from tab completion and `--help` output.
+
 ## CommandActivator
 
-Control whether a command is visible/available:
+Control whether an entire command is visible and available:
 
 ```java
+public interface CommandActivator {
+    boolean isActivated(ParsedCommand command);
+}
+```
+
+### Example: Admin-Only Commands
+
+```java
+import org.aesh.command.activator.CommandActivator;
+import org.aesh.command.impl.internal.ParsedCommand;
+
 public class AdminCommandActivator implements CommandActivator {
 
     @Override
-    public boolean isActivated(CommandInvocation invocation) {
-        // Only show admin commands if user is admin
-        return isAdmin(invocation);
-    }
-
-    private boolean isAdmin(CommandInvocation invocation) {
-        // Check if user has admin privileges
-        // This could check environment variables, config files, etc.
-        return System.getProperty("user.role", "user").equals("admin");
+    public boolean isActivated(ParsedCommand command) {
+        return "admin".equals(System.getProperty("user.role", "user"));
     }
 }
 ```
 
-Usage:
-
 ```java
 @CommandDefinition(
     name = "shutdown",
@@ -92,56 +114,47 @@ public class ShutdownCommand implements Command<CommandInvocation> {
 }
 ```
 
-## Conditional Validation
+The `shutdown` command only appears in tab completion and help when `user.role` is `admin`. Users without admin role cannot discover or execute it.
 
-Use activators to conditionally require options:
+## Conditional Required Options
+
+Combine activators with `required = true` to make options conditionally required:
 
 ```java
 public class OutputFileActivator implements OptionActivator {
 
     @Override
-    public boolean isActivated(CompleterInvocation invocation) {
-        MyCommand cmd = (MyCommand) invocation.getCommand();
-        // Output file option only active when not verbose
-        return !cmd.verbose;
+    public boolean isActivated(ParsedCommand parsedCommand) {
+        // Output file only required when not in verbose mode
+        return parsedCommand.findLongOptionNoActivatorCheck("verbose")
+                .getValue() == null;
     }
 }
 
-@CommandDefinition(name = "process")
+@CommandDefinition(name = "process", description = "Process data")
 public class ProcessCommand implements Command<CommandInvocation> {
 
-    @Option(name = "verbose", hasValue = false, description = "Verbose output")
+    @Option(name = "verbose", hasValue = false, description = "Verbose output to console")
     private boolean verbose = false;
 
     @Option(
         name = "output",
         activator = OutputFileActivator.class,
         required = true,
-        description = "Output file (required unless verbose)"
+        description = "Output file (required unless --verbose)"
     )
     private String outputFile;
 
     @Override
     public CommandResult execute(CommandInvocation invocation) {
+        if (verbose) {
+            invocation.println("Processing... (verbose output)");
+        } else {
+            invocation.println("Writing output to " + outputFile);
+        }
         return CommandResult.SUCCESS;
     }
 }
 ```
 
-When `--verbose` is used, the `--output` option is hidden and not required.
-
-## Accessing Runtime Context
-
-Activators can access the Aesh context:
-
-```java
-public class ContextAwareActivator implements OptionActivator {
-
-    @Override
-    public boolean isActivated(CompleterInvocation invocation) {
-        AeshContext context = invocation.getAeshContext();
-        // Access runtime context for more complex conditions
-        return context.someCondition();
-    }
-}
-```
+When `--verbose` is used, `--output` is deactivated and not required. Without `--verbose`, `--output` is required.

content/docs/aesh/command-invocation.md

@@ -842,8 +842,7 @@ public class MyApplication {
                         .create();
 
         // Configure settings with the custom invocation provider
-        Settings<MyCommandInvocation, CommandInvocation, 
-                 CommandInputProcessor, CommandProcessorContext, CommandOutput> settings = 
+        Settings<MyCommandInvocation> settings = 
                 SettingsBuilder.<MyCommandInvocation>builder()
                         .commandRegistry(registry)
                         .commandInvocationProvider(invocationProvider)

content/docs/aesh/converters.md

@@ -5,50 +5,105 @@ title: 'Converters'
 weight: 10
 ---
 
-Converters transform string input into custom types.
+Converters transform the raw string input from the command line into the Java type your option or argument expects. They run automatically when Æsh populates your command object.
 
 ## Converter Interface
 
-Implement the `Converter<T>` interface:
+```java
+public interface Converter<T, C extends ConverterInvocation> {
+    T convert(C converterInvocation) throws OptionValidatorException;
+}
+```
+
+The `ConverterInvocation` provides:
+- `getInput()` -- the raw string value from the command line
+- `getAeshContext()` -- the current Æsh context
+
+## Built-in Converters
+
+Æsh converts these types automatically -- no converter needed:
+
+- `String`
+- `int` / `Integer`, `long` / `Long`, `short` / `Short`, `byte` / `Byte`
+- `float` / `Float`, `double` / `Double`
+- `boolean` / `Boolean` (accepts `true`, `false`, `yes`, `no`)
+- `char` / `Character`
+- `File`, `Path`
+- Any `Enum` type (matched by name, case-insensitive)
+
+## Enum Conversion
+
+Enums work out of the box:
 
 ```java
-public interface Converter<T> {
-    T convert(String input) throws ConverterException;
+public enum LogLevel {
+    DEBUG, INFO, WARN, ERROR
+}
+
+@CommandDefinition(name = "log", description = "Configure logging")
+public class LogCommand implements Command<CommandInvocation> {
+
+    @Option(description = "Log level")
+    private LogLevel level = LogLevel.INFO;
+
+    @Override
+    public CommandResult execute(CommandInvocation invocation) {
+        invocation.println("Log level: " + level);
+        return CommandResult.SUCCESS;
+    }
 }
 ```
 
-## Custom Type Conversion
+```
+$ log --level DEBUG
+Log level: DEBUG
+```
+
+Tab completion for enum values is also automatic.
+
+## Custom Converters
 
-Convert a string to a custom class:
+Write a converter when you need a type that isn't built in. Implement `Converter<T, ConverterInvocation>`:
 
 ```java
-public class DurationConverter implements Converter<Duration> {
+import org.aesh.command.converter.Converter;
+import org.aesh.command.converter.ConverterInvocation;
+import org.aesh.command.validator.OptionValidatorException;
+
+import java.time.Duration;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class DurationConverter implements Converter<Duration, ConverterInvocation> {
+
+    private static final Pattern PATTERN = Pattern.compile("(\\d+)([smhd])");
 
     @Override
-    public Duration convert(String input) throws ConverterException {
-        try {
-            String[] parts = input.split("(?<=\\D)(?=\\d)");
-            long value = Long.parseLong(parts[0]);
-            String unit = parts[1].toLowerCase();
-            
-            switch (unit) {
-                case "s": return Duration.ofSeconds(value);
-                case "m": return Duration.ofMinutes(value);
-                case "h": return Duration.ofHours(value);
-                default: throw new ConverterException("Invalid unit: " + unit);
-            }
-        } catch (Exception e) {
-            throw new ConverterException("Invalid duration: " + input + 
-                ". Use format like: 30s, 5m, 2h");
+    public Duration convert(ConverterInvocation invocation) throws OptionValidatorException {
+        String input = invocation.getInput();
+        Matcher matcher = PATTERN.matcher(input.toLowerCase());
+
+        if (!matcher.matches()) {
+            throw new OptionValidatorException("Invalid duration: " + input +
+                ". Use format like: 30s, 5m, 2h, 1d");
+        }
+
+        long value = Long.parseLong(matcher.group(1));
+        switch (matcher.group(2)) {
+            case "s": return Duration.ofSeconds(value);
+            case "m": return Duration.ofMinutes(value);
+            case "h": return Duration.ofHours(value);
+            case "d": return Duration.ofDays(value);
+            default:  throw new OptionValidatorException("Unknown unit: " + matcher.group(2));
         }
     }
 }
 ```
 
-Usage:
+Use it with `@Option`:
 
 ```java
-@CommandDefinition(name = "timeout")
+@CommandDefinition(name = "timeout", description = "Set a timeout")
 public class TimeoutCommand implements Command<CommandInvocation> {
 
     @Option(
@@ -60,47 +115,29 @@ public class TimeoutCommand implements Command<CommandInvocation> {
 
     @Override
     public CommandResult execute(CommandInvocation invocation) {
-        invocation.println("Timeout: " + duration.toSeconds() + " seconds");
+        invocation.println("Timeout set to " + duration.toSeconds() + " seconds");
         return CommandResult.SUCCESS;
     }
 }
 ```
 
-Usage: `timeout --duration 5m`
-
-## Built-in Converters
-
-Æsh includes converters for common types:
-- `String`
-- `int`, `Integer`
-- `long`, `Long`
-- `float`, `Float`
-- `double`, `Double`
-- `boolean`, `Boolean`
-- `File`
-- `Path`
-
-## Enum Conversion
+```
+$ timeout --duration 5m
+Timeout set to 300 seconds
+```
 
-Enums are automatically converted:
+## Error Handling
 
-```java
-public enum LogLevel {
-    DEBUG, INFO, WARN, ERROR
-}
+When conversion fails, throw `OptionValidatorException` with a message describing what went wrong and what the user should provide instead. Æsh displays the message to the user and aborts command parsing:
 
-@CommandDefinition(name = "log")
-public class LogCommand implements Command<CommandInvocation> {
+```
+$ timeout --duration abc
+Invalid duration: abc. Use format like: 30s, 5m, 2h, 1d
+```
 
-    @Option(description = "Log level")
-    private LogLevel level = LogLevel.INFO;
+## Converter vs Validator
 
-    @Override
-    public CommandResult execute(CommandInvocation invocation) {
-        invocation.println("Log level: " + level);
-        return CommandResult.SUCCESS;
-    }
-}
-```
+- **Converters** transform the input string into a typed value. They answer: *"What does this string mean?"*
+- **Validators** check whether a value is acceptable. They answer: *"Is this value allowed?"*
 
-Usage: `log --level DEBUG`
+Converters run first. If conversion succeeds, validators run next. Use a converter when you need a custom type; use a [Validator](../validators) when the type is standard but the allowed values are restricted (e.g., port must be 1-65535).