luigidemasi opened a new issue, #171: URL: https://github.com/apache/camel-kit/issues/171
## Description Migrate the Camel Kit CLI from Picocli to Aesh to align with JBang and the planned Camel JBang migration. Use [Aesh 3.19](https://github.com/aeshell/aesh/releases/tag/v3.19) as the migration baseline and align the resolved dependency version with the selected Camel host release. Both entry points must continue to work: standalone `camel-kit` and the `camel kit` plugin. Preserve one-shot execution and the existing CLI contract. Aesh's interactive console and completion capabilities provide future opportunities, but adding a REPL is a separate change. **Compatibility decision:** the first Aesh-based Camel Kit release may require the Camel release that adopts Aesh. Supporting older Picocli-based Camel JBang hosts is not required. Establish and document the exact minimum host version before release. ## Expected Behavior Existing commands retain their names, options, argument semantics, generated assets, machine-readable output and exit-code meanings while executing through Aesh. Business logic remains in the existing services/controllers. The standalone and plugin entry points expose equivalent behavior. ## Implementation Scope - Migrate root/subcommand registration, command annotations and execution, option/positional binding, converters, help/version handling, and output/error wiring in `kit/camel-kit-core`. - Adapt `kit/camel-jbang-plugin-kit` to Camel's final Aesh plugin SPI, update the minimum supported host metadata, and verify the packaged plugin against that host. - Update standalone launcher/dependency wiring, parser-dependent tests, contributor guidance and the rule files that currently prescribe Picocli. - Preserve the current JLine/TamboUI rendering initially. Verify terminal ownership and cleanup when using Aesh's non-interactive runner; replacing the terminal backend is a separate change. - Follow the repository's version-pin conventions. Review the current `camel.version` → `camel.main.version` coupling so raising the CLI host minimum does not inadvertently change the supported/default Camel versions of generated integrations. ## Migration Sequence 1. Capture the current argument, help, stdout/stderr, exit-code and generated-output contracts for both entry points. 2. Implement a bounded Aesh spike covering a nested command, `init` property options, and the difficult Ship bindings below. Resolve incompatibilities before porting the whole command tree. 3. Migrate ordinary commands, then Ship, while retaining the existing service/controller behavior and test assertions. 4. Integrate the final Camel plugin API and run packaged standalone/plugin acceptance, platform checks and documentation updates. ## Compatibility Cases That Must Be Preserved - **Ordered Ship context:** `ship --text first --document requirements.md --text last` must preserve interleaving. Picocli's repeating composite `@ArgGroup` has no equivalent annotation identified in Aesh 3.19. Separate text/document lists are insufficient; prove a bounded binding adaptation or obtain upstream support. - **Operation validation:** Ship's mutually exclusive operations and dependent options must fail before state writes or worker launch. Preserve usage-error exit code 2; Aesh command-validator exceptions default to exit 1. - **Argument files and literal values:** preserve Ship's literal `@` input and the intended argument-file policy elsewhere. The plugin must not change unrelated Camel commands' parsing. Pass tokenized arguments through the argv API, preserving empty strings, quotes, spaces, commas and shell metacharacters. - **Collection arity:** preserve `init -p` accepting multiple values per occurrence and Ship's repeatable single-value property option. Choose `@OptionList` separators/consumption rules explicitly. - **Flags and defaults:** preserve nullable Boolean semantics, explicit false values, defaults, duplicate-option behavior, required arguments and hidden options. Aesh defaults to last-value-wins for repeated scalar options; configure strictness where required by the existing contract. - **Help/version and converters:** preserve `-h`/`--help` and `-V`/`--version` (Aesh's generated version shorthand is `-v`), dynamic artifact version lookup, Ship's four custom converters, and qualified resume-command text. ## Acceptance Criteria - [ ] Standalone and plugin command trees are equivalent for `init`, `doctor`, `doc`, `graph`, `plan`, `nextId` and `ship`, including nested commands. - [ ] Regression tests cover the compatibility cases above, including invalid requests causing no side effects and mixed repeated context order. - [ ] `doctor --json`, graph JSON and Ship JSON remain clean when redirected; stdout/stderr separation and `--silent` behavior are preserved. - [ ] Init generates equivalent assets and the correct command prefix through both entry points. - [ ] Packaged standalone execution and plugin discovery/loading work with the selected Aesh-based Camel release; the minimum host version is recorded. - [ ] Headless/redirected operation and terminal cleanup are verified across supported JDKs and operating systems, including Windows path/quoting behavior and existing TUI behavior. - [ ] Existing tests remain effective, and `./mvnw -B clean install` plus `./mvnw -B -Psourcecheck validate` pass. Do not run Maven in parallel. - [ ] Resolved dependency size and representative cold/warm CLI startup are measured; no size or performance improvement is assumed from framework benchmarks. - [ ] Public documentation, contributor/rule guidance and `CHANGELOG.md` reflect the migration and compatibility requirements. ## Website Impact **Required.** Update `docs/modules/ROOT/**` for installation/minimum Camel host, CLI reference/help, and any intentional behavior changes. Include the documentation in the implementation change, or link a `documentation` follow-up on `apache/camel-kit` before closing this issue. Documentation belongs in the Antora component, not the retired standalone website. ## Additional Context The assessment inspected Kit main `6f642fb3`: 35 production Java files and 15 test files directly reference Picocli. Sixteen isolated probes against the published Aesh 3.19/Picocli 4.7.7 JARs on Linux/JDK 25 confirmed the sampled parsing differences; these are framework probes, not end-to-end migration acceptance. JBang's migration is merged in [jbangdev/jbang#2453](https://github.com/jbangdev/jbang/pull/2453). Camel main `3bc999e9` still exposes Picocli in its [plugin SPI](https://github.com/apache/camel/blob/3bc999e99029efa34a5cd800d7aadc4cbc3008fd/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/common/Plugin.java); coordinate with the upstream migration and final host release. [Aesh's migration guide](https://aeshell.github.io/docs/aesh/migrating-from-picocli/) describes the available annotation/runtime APIs. _AI-generated by OpenAI Codex on behalf of @luigidemasi._ -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
