Add onReady callback to AeshConsoleRunner (#603)

Fires a Runnable callback after readline is armed and ready to accept
input, but before connection.openBlocking() blocks the calling thread.
This gives test frameworks and embedders a reliable signal that the REPL
is ready to receive commands, eliminating the need for Thread.sleep()
between starting the REPL and sending the first command.

ReadlineConsole: onReadyCallback field + setOnReadyCallback(Runnable)
AeshConsoleRunner: onReady(Runnable) builder method wired via start()

Author: stalep

aesh/src/main/java/org/aesh/AeshConsoleRunner.java

@@ -48,6 +48,7 @@ public class AeshConsoleRunner {
     private Prompt prompt;
     private ReadlineConsole console;
     private Connection connection;
+    private Runnable onReady;
 
     private AeshConsoleRunner() {
     }
@@ -196,6 +197,33 @@ public AeshConsoleRunner promptSupplier(Supplier<Prompt> supplier) {
         return this;
     }
 
+    /**
+     * Set a callback that fires once after readline is armed and ready to
+     * accept input, but before the blocking input loop starts. Intended for
+     * test frameworks and embedders that need a reliable "REPL is ready"
+     * signal before sending the first command.
+     *
+     * <p>
+     * Example:
+     *
+     * <pre>{@code
+     * CountDownLatch ready = new CountDownLatch(1);
+     * new Thread(() -> AeshConsoleRunner.builder()
+     *         .command(MyCommand.class)
+     *         .onReady(ready::countDown)
+     *         .start()).start();
+     * ready.await(5, TimeUnit.SECONDS); // guaranteed to be armed now
+     * }</pre>
+     *
+     * @param callback the callback to invoke when the console is ready
+     * @return this builder
+     * @since 3.17
+     */
+    public AeshConsoleRunner onReady(Runnable callback) {
+        this.onReady = callback;
+        return this;
+    }
+
     public AeshConsoleRunner addExitCommand() {
         ensureRegistryBuilderInitialized();
         try {
@@ -211,6 +239,8 @@ public void start() {
             init();
             if (prompt != null)
                 console.setPrompt(prompt);
+            if (onReady != null)
+                console.setOnReadyCallback(onReady);
             try {
                 console.start();
             } catch (IOException e) {

aesh/src/main/java/org/aesh/console/ReadlineConsole.java

@@ -115,6 +115,7 @@ public class ReadlineConsole implements Console, Consumer<Connection> {
 
     private ShellImpl shell;
     private CommandContext commandContext;
+    private Runnable onReadyCallback;
 
     private final EnumMap<ReadlineFlag, Integer> readlineFlags = new EnumMap<>(ReadlineFlag.class);
 
@@ -268,6 +269,9 @@ public void accept(Connection connection) {
 
         this.runtime = generateRuntime();
         read(this.connection, readline);
+        // Notify embedders/test frameworks that readline is armed and ready (#603)
+        if (onReadyCallback != null)
+            onReadyCallback.run();
         this.connection.openBlocking();
     }
 
@@ -495,6 +499,19 @@ public void setPrompt(String prompt) {
             this.prompt = new Prompt(prompt);
     }
 
+    /**
+     * Set a callback that fires once after readline is armed and ready to
+     * accept input, but before the blocking input loop starts.
+     * Intended for test frameworks and embedders that need a reliable
+     * "REPL is ready" signal.
+     *
+     * @param callback the callback to invoke when the console is ready
+     * @since 3.17
+     */
+    public void setOnReadyCallback(Runnable callback) {
+        this.onReadyCallback = callback;
+    }
+
     @Override
     public AeshContext context() {
         return context;

aesh/src/test/java/org/aesh/AeshConsoleRunnerTest.java

@@ -22,6 +22,9 @@
 import static org.aesh.terminal.utils.Config.getLineSeparator;
 import static org.junit.Assert.assertTrue;
 
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
 import org.aesh.command.Command;
 import org.aesh.command.CommandDefinition;
 import org.aesh.command.CommandResult;
@@ -202,6 +205,34 @@ public CommandResult execute(CommandInvocation commandInvocation) {
         }
     }
 
+    @Test
+    public void testOnReadyFiresWhenConsoleIsArmed() throws Exception {
+        TestConnection connection = new TestConnection();
+        CountDownLatch readyLatch = new CountDownLatch(1);
+        CountDownLatch commandLatch = new CountDownLatch(1);
+
+        // Start the blocking REPL on a background thread
+        Thread replThread = new Thread(() -> AeshConsoleRunner.builder()
+                .connection(connection)
+                .command(HelloCommand.class)
+                .addExitCommand()
+                .commandExecutionListener((line, result, durationMs) -> commandLatch.countDown())
+                .onReady(readyLatch::countDown)
+                .start());
+        replThread.setDaemon(true);
+        replThread.start();
+
+        // onReady must fire before the REPL thread blocks in openBlocking()
+        assertTrue("onReady should fire within 5 seconds", readyLatch.await(5, TimeUnit.SECONDS));
+
+        // Readline is now armed — send a command immediately, no sleep needed
+        connection.read("hello" + getLineSeparator());
+        assertTrue("Command should execute", commandLatch.await(5, TimeUnit.SECONDS));
+        assertTrue("Output should contain greeting", connection.getOutputBuffer().contains("Hello"));
+
+        connection.read("exit" + getLineSeparator());
+    }
+
     private static void assertClosedWithin(TestConnection connection, long timeoutMs) throws InterruptedException {
         long deadline = System.currentTimeMillis() + timeoutMs;
         while (!connection.closed() && System.currentTimeMillis() < deadline) {