citrusframework / citrusframework/citrus

Port Citrus JBang from Picocli to Aesh

Open
#1,574 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Java
Stars
485
Forks
155
Avg merge
2d 10h
Merged PRs (30d)
7

Description

Description

Replace Picocli with Aesh as the CLI framework for the Citrus JBang tool (tools/jbang). This follows the same migration that JBang itself completed, as described in From Picocli to Aesh: How Porting JBang's CLI Made Everything Better.

Motivation

Picocli relies on runtime reflection for command and option discovery, which adds startup overhead — especially under GraalVM native image. Aesh uses compile-time annotation processing to generate command metadata as switch statements, eliminating reflection at startup and classpath scanning.

Key benefits observed in JBang's migration:

  • ~5x faster native startup (33ms -> 6ms) and ~2x faster on JDK (228ms -> 109ms)
  • Practical tab-completion — fast enough to run per-keypress without perceptible lag
  • GraalVM-friendly — no reflection configuration needed for native images
  • Zero external dependencies — Aesh relies solely on the JDK
  • Alignment with JBang — since Citrus JBang runs on JBang, aligning on the same CLI framework reduces friction

Scope

The tools/jbang module currently uses Picocli 4.7.7 with the following command classes that need porting:

  • CitrusJBangMain — root command
  • CitrusCommand — abstract base class (Callable<Integer>)
  • Init, Inspect, Run, ListTests, Complete — top-level commands
  • Agent, AgentStart, AgentRun, AgentStop — agent subcommand group

Migration involves:

  1. Replace info.picocli:picocli dependency with Aesh
  2. Port @Command / @CommandLine.Option / @CommandLine.Parameters annotations to Aesh equivalents (@CommandDefinition, @Option, @Argument)
  3. Replace Callable<Integer> pattern with Aesh's command execution model
  4. Port tab-completion support (Complete.java currently uses picocli.AutoComplete)
  5. Update CitrusJBang.java JBang script directives (//DEPS)

The connectors/citrus-jbang-connector module does not use Picocli directly and should not require changes.

References

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in tools/jbang by inspecting the Picocli dependency and the listed command classes, then compare their annotations and execution flow with Aesh. Update the commands, completion support, and CitrusJBang.java directives so the existing CLI behavior works without Picocli; leave connectors/citrus-jbang-connector unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
cli
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.