Tail tip suggestions — show parameter hints after cursor

[stalep]

Summary

Display contextual parameter hints (tail tips) after the cursor as the user types commands, showing expected arguments and options.

Description

When typing a command, show dimmed hint text after the cursor indicating what parameters are expected. For example:

$ git commit [-m <message>] [-a] [--amend]
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ tail tip (dimmed)

The tail tip would update dynamically based on:

• Which command is being typed
• Which options have already been provided
• The current argument position

This leverages the existing ghost text rendering infrastructure in aesh-readline, but requires command metadata from the aesh command framework (@Option, @Argument annotations) to generate the tips.

Implementation Notes

• Use @Option and @Argument metadata to build tip text
• Show remaining required options prominently
• Dim optional parameters
• Update on each keystroke as the parser identifies the current position
• Builds on aesh-readline's SuggestionProvider / ghost text infrastructure

Priority

High — significantly improves command discoverability.

[stalep]

Implementation Plan

After analysis, here is how this could be implemented. Keeping this for future reference.

What tail tips are

Tail tips show the remaining parameter synopsis after the cursor as dimmed ghost text. Unlike the existing command auto-suggest (which completes the current word), tail tips show what comes next structurally:

$ deploy --force |[-e <environment>] <application>
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ tail tip (dimmed)

As the user fills in parameters, the tail tip updates to show only what's still needed:

$ deploy --force -e prod |<application>
                          ^^^^^^^^^^^^^ tail tip (dimmed)

Scope: Interactive REPL only

Tail tips only apply to the interactive ReadlineConsole path (CLI/REPL mode). They do not apply to:

• AeshRuntimeRunner (single-shot runtime): No readline loop, no SuggestionProvider chain — the feature naturally doesn't exist in this path. No extra guarding needed.
• Shell completion scripts (--aesh-complete, --aesh-completion): Shell scripts have their own display mechanisms.

This is enforced structurally: TailTipSuggestionProvider is only instantiated and wired inside ReadlineConsole.

Configuration: Opt-in via Settings

Tail tips are a new UX behavior on every keystroke. They should be off by default and explicitly enabled:

SettingsBuilder.builder()
    .tailTipSuggestions(true)   // default: false
    .build();

The setting controls whether ReadlineConsole adds a TailTipSuggestionProvider to the suggestion chain. When false, no tail tip provider is created — zero overhead. Once the feature is stable, a future version can flip the default to true.

Key design decisions

1. Tail tips vs auto-suggest: priority ordering

The ghost text area can only show one thing at a time. The CompositeSuggestionProvider in readline chains providers and returns the first non-null result. The ordering:

1. HistorySuggestionProvider — history auto-suggest (highest priority)
2. CommandSuggestionProvider — command/option name auto-suggest
3. TailTipSuggestionProvider — tail tips (lowest priority)

Priority resolution by cursor state:

• Mid-word (cursor after dep): CommandSuggestionProvider returns loy → tail tip not reached
• After space (cursor after deploy ): auto-suggest providers return null → tail tip shows [-e <environment>] [--force] <application>
• After -- (cursor after deploy --): auto-suggest returns option completion → tail tip not reached

This falls out naturally from the composite chain — no special coordination needed.

2. Ghost text rendering

Tail tips reuse the existing ghost text infrastructure (showGhostText, clearGhostText). The rendering is identical: dimmed text after cursor, cleared on any input.

One UX concern: Right arrow currently accepts ghost text into the buffer. For tail tips, accepting [-e <environment>] literally is not useful. Two options:

• Accept it: Users quickly learn that Right arrow after a space inserts template text. Not harmful (they can undo). Fish shell works similarly.
• Add non-acceptable ghost text: A small readline change (~5 lines) adds a flag so acceptGhostText() clears instead of inserts when the content is a tail tip. Cleaner UX but requires a readline release.

Recommendation: Start with accepting it (simpler, no readline change). Add the non-acceptable flag later if users find it confusing.

3. Building the remaining synopsis

The tail tip shows only parameters not yet provided. This requires parsing the current buffer (completion-mode parse) to determine consumed options:

1. Parse the buffer through the command's parser in COMPLETION mode
2. Collect options where getValue() == null and isActivated()
3. Build a mini-synopsis from remaining options using the same format as buildSynopsisString()
4. Check argument/arguments status for positional parameters

Implementation steps

Step 1: TailTipSuggestionProvider (~120 lines)

Location: aesh/src/main/java/org/aesh/command/impl/completer/TailTipSuggestionProvider.java

A SuggestionProvider that:

1. Returns null if buffer is empty, doesn't end with space, or command isn't recognized (let other providers handle it)
2. Resolves the command from the registry
3. Runs a lightweight completion-mode parse to identify consumed options
4. Calls buildRemainingSynopsis() on the ProcessedCommand
5. Returns the tip string

Step 2: ProcessedCommand.buildRemainingSynopsis() (~40 lines)

Similar to buildSynopsisString() but filters to options where getValue() == null. Uses the same formatting: short flag cluster, negatable format, exclusive pipes, value placeholders.

Step 3: Settings integration (~10 lines)

Add tailTipSuggestions boolean to Settings/SettingsBuilder, default false.

Step 4: Wire into ReadlineConsole (~10 lines)

When settings.tailTipSuggestions() is true, add TailTipSuggestionProvider as the last provider in the composite chain.

Step 5 (optional): Non-acceptable ghost text (~15 lines, readline change)

Add a nonAcceptable flag to ghost text in AeshConsoleBuffer. When acceptGhostText() is called and the flag is set, clear instead of insert. TailTipSuggestionProvider would set this flag via a new showTailTip(String) method.

Edge cases

• Group commands: After git , show subcommand names. After git commit , show commit's remaining options.
• All required satisfied: Show only optional options, or nothing if everything is provided.
• stopAtFirstPositional: After first positional, show [<args>...] or nothing.
• Performance: Cache last parse result; only re-parse when buffer changes. Completion-mode parsing is already fast (no validation, no population).
• Terminal width: Truncate with ... if tip exceeds available width.

Estimated scope

• TailTipSuggestionProvider: ~120 lines
• ProcessedCommand.buildRemainingSynopsis(): ~40 lines
• ReadlineConsole + Settings wiring: ~20 lines
• Optional readline change: ~15 lines
• Tests: ~150 lines
• Total: ~350 lines

Risk

Low — opt-in feature, uses existing ghost text infrastructure, no impact on runtime path or shell scripts. Performance concern (parse per keystroke) mitigated by caching.