Migrate the client from picocli to aesh

[cmoulliard]

TODO

• Migrate the client from picocli to aesh

[cmoulliard]

Test results using the following PR's skills: #13

• Test performed using Claude - opus 4.6 on Vertex AI
• SKILL created by Claude from - Use a SKILL based on the https://aeshell.github.io/docs/aesh/migrating-from-picocli/
• SKILL installed using npx: npx skills add ./client/skills/migrate-picocli-to-aesh/
• Command executed:

acp -a claude-acp \
   -s "/Users/cmoullia/.agents/skills/migrate-picocli-to-aesh" \
   -p "migrate picocli to aesh. 
   When requested proceed to the migration. 
   After migration, verify the project compiles with ./mvnw compile and fix any errors.
   Then run ./mvnw test and fix any test failures.
   If you need to delete code or files, explain why you are deleting them and what you are replacing them with.
   If anything could not be converted/migrated explain why - do not just delete/remove it without explaining.
   Include a summary of the migration in the end of the output."

Results

All 6 verification checks pass:

| # | Check | Result | Notes |
|---|-------|--------|-------|
| 1 | **Builds** | PASS | `mvn clean package -DskipTests -pl client` — exit code 0 |
| 2 | **No picocli deps** | PASS | Zero `info.picocli` dependencies in pom.xml |
| 3 | **Has Aesh** | PASS | `org.aesh:aesh:3.6.1` present |
| 4 | **Tests pass** | PASS | No tests exist (N/A) |
| 5 | **CLI runs** | PASS | `--help` shows all options; `reg`, `reg list` work correctly |
| 6 | **No leftover picocli imports** | PASS | Zero `import picocli` in sources |
14:43:17,888 INFO  [AcpClientCommand] [Update] usage_update: UsageUpdate[meta=null, used=128913, size=200000, cost=null]
14:43:17,902 INFO  [AcpClientCommand] [Plan] 5 steps:
14:43:17,903 INFO  [AcpClientCommand]   - Migrate client/pom.xml: replace picocli deps with Aesh [COMPLETED]
14:43:17,903 INFO  [AcpClientCommand]   - Migrate Java source code from picocli to Aesh annotations [COMPLETED]
14:43:17,903 INFO  [AcpClientCommand]   - Create QuarkusMain entry point for Aesh [COMPLETED]
14:43:17,903 INFO  [AcpClientCommand]   - Cleanup leftover picocli artifacts [COMPLETED]
14:43:17,903 INFO  [AcpClientCommand]   - Verify build compiles and tests pass [COMPLETED]
14:43:17,908 INFO  [StdioAcpClientTransport] STDERR: No onPostToolUseHook found for tool use ID: toolu_vrtx_01WkpPXYLoiZEcs3M7h3obo1
14:43:17,910 INFO  [AcpClientCommand] [Plan] 5 steps:
14:43:17,910 INFO  [AcpClientCommand]   - Migrate client/pom.xml: replace picocli deps with Aesh [COMPLETED]
14:43:17,910 INFO  [AcpClientCommand]   - Migrate Java source code from picocli to Aesh annotations [COMPLETED]
14:43:17,910 INFO  [AcpClientCommand]   - Create QuarkusMain entry point for Aesh [COMPLETED]
14:43:17,910 INFO  [AcpClientCommand]   - Cleanup leftover picocli artifacts [COMPLETED]
14:43:17,910 INFO  [AcpClientCommand]   - Verify build compiles and tests pass [COMPLETED]
14:43:18,993 INFO  [AcpClientCommand] [Update] usage_update: UsageUpdate[meta=null, used=128932, size=200000, cost=null]
## Step 4: Migration Review (Self-Reflection)

**1. What migrated cleanly?**
- All `@CommandLine.Option` → Aesh `@Option` (direct 1:1 mapping for String/Integer fields)
- `@CommandLine.Parameters` → `@Argument` (single positional params)
- `@CommandLine.Command` → `@CommandDefinition` (leaf commands)
- `@CommandLine.Command(subcommands=...)` → `@GroupCommandDefinition(groupCommands=...)` (group commands)
- `implements Runnable` → `implements Command<CommandInvocation>`
- `System.out.println` → `invocation.println` / `System.err.println` → `invocation.println`
- `System.exit(1)` → `return CommandResult.FAILURE`

**2. What required manual judgment?**
- **Quarkus integration**: `@TopCommand` + `quarkus-picocli` → `@QuarkusMain` + `quarkus-arc` + `AeshRuntimeRunner`. No direct equivalent exists; chose `@QuarkusMain` to maintain Quarkus lifecycle.
- **`@CommandLine.Spec` usage**: RegistryCommand used picocli's spec to print usage. Replaced with manual usage text in the `execute()` method.
- **Readline version conflict**: Quarkus BOM downgrades `readline` from 3.6 → 2.6, breaking Aesh 3.6.1 at runtime. Added explicit version override.
- **`System.out.print` in callbacks**: Session update handler prints streaming content. Stored `CommandInvocation` as instance field for use in callback lambdas.
- **`requireEnv` static method**: Used `System.exit(1)` — changed to throw `RuntimeException`, caught in `execute()` to return `CommandResult.FAILURE`.

**3. What was left as TODO?**
None — all code was fully migrated.

**4. Was any code removed?**

| File | What was removed | Justification |
|------|-----------------|---------------|
| AcpClientCommand.java | `ManPageGenerator.class` subcommand | Picocli-specific codegen tool (`picocli.codegen.docgen.manpage.ManPageGenerator`). No Aesh equivalent. The commented-out Maven plugin using it was also removed. |
| AcpClientCommand.java | `GenerateCompletion.class` subcommand | Picocli-specific shell completion generator (`picocli.AutoComplete.GenerateCompletion`). Aesh replaces this with built-in `--aesh-completion` flag — no subcommand needed. |
| AcpClientCommand.java | `@TopCommand` annotation | Quarkus picocli-specific annotation. Replaced by `@QuarkusMain` entry point class `AcpMain.java`. |
| AcpClientCommand.java | `--wks` option alias | Picocli supports multiple long names; Aesh supports one. Kept `--workspace-path` as primary. |
| client/pom.xml | `quarkus-picocli` dependency | Replaced by `quarkus-arc` + `aesh` |
| client/pom.xml | `picocli-codegen` dependency | No longer needed |
| client/pom.xml | `picocli.version` property | Replaced by `aesh.version` |
| client/pom.xml | Commented-out ManPageGenerator/asciidoctor plugins | Picocli-specific build plugins, no longer applicable |

**5. What checks failed initially?**
- **Missing transitive dependencies**: After removing `quarkus-picocli`, `org.jboss.logging` and `io.quarkus.runtime` packages were missing. Fixed by adding `quarkus-arc` dependency.
- **Readline version mismatch**: Quarkus BOM managed `readline` to v2.6 while `aesh` 3.6.1 requires v3.6. This caused `NoClassDefFoundError: org/aesh/terminal/KeyAction` at runtime. Fixed by overriding `readline` version in `dependencyManagement`.

**6. What's missing from the skill references?**
- **Quarkus integration path**: The skill doesn't cover migrating from `quarkus-picocli` to Aesh within Quarkus apps (using `@QuarkusMain`).
- **Quarkus BOM version conflicts**: The Quarkus BOM manages `readline` and can downgrade it, breaking Aesh. This should be documented.
- **`@GroupCommandDefinition` limitations**: No `generateHelp` or `version` attributes exist on `@GroupCommandDefinition` (unlike `@CommandDefinition`). The skill assumes both annotations have the same attributes.
- **Multiple long name aliases**: Picocli supports `names = {"--wks", "--workspace-path"}`. Aesh only supports one long name. This lossy mapping should be documented.

---

## Migration Report: acp-java-client

### Summary
- Agent: Claude Code
- Model: claude-opus-4-6
- Modules completed: 4/4
- Checks passed: 6/6

### Changes by Module

| Module | Files changed | Key changes |
|--------|--------------|-------------|
| build | `client/pom.xml`, `client/src/main/resources/application.properties` | Replaced `quarkus-picocli` + `picocli-codegen` with `quarkus-arc` + `aesh:3.6.1`. Added `readline:3.6` version override to fix Quarkus BOM conflict. Removed picocli properties and commented-out plugins. |
| code | `AcpClientCommand.java`, `RegistryCommand.java`, `InstallCommand.java`, `ListAgentsCommand.java`, `RemoveCommand.java` + new `AcpMain.java` | Migrated all annotations (`@Command` → `@CommandDefinition`/`@GroupCommandDefinition`), interfaces (`Runnable` → `Command<CommandInvocation>`), options, arguments, execution model, and output. Created `@QuarkusMain` entry point. |
| testing | — | No tests exist — module skipped |
| cleanup | All source files verified | Zero picocli imports remaining, zero picocli dependencies |

### Validation Results

| Check | Result | Notes |
|-------|--------|-------|
| Builds | PASS | `mvn clean package -DskipTests -pl client` |
| No picocli deps | PASS | Zero `info.picocli` in pom.xml |
| Has Aesh | PASS | `org.aesh:aesh:3.6.1` present |
| Tests pass | PASS | No tests exist (N/A) |
| CLI runs | PASS | `--help`, `reg`, `reg list` all work correctly |
| No leftover imports | PASS | Zero `import picocli` in sources |

### Unmigrated Code (TODOs)

| File | Line | What | Why not migrated |
|------|------|------|-----------------|
| — | — | — | All code fully migrated |

### Removed Code

| File | What was removed | Justification |
|------|-----------------|---------------|
| AcpClientCommand.java | `ManPageGenerator.class` subcommand | Picocli-specific codegen — no Aesh equivalent exists |
| AcpClientCommand.java | `GenerateCompletion.class` subcommand | Picocli-specific — Aesh has built-in `--aesh-completion` flag |
| AcpClientCommand.java | `@TopCommand` annotation | Quarkus picocli-specific — replaced by `@QuarkusMain` |
| AcpClientCommand.java | `--wks` option alias | Aesh supports only one long name per option |
| client/pom.xml | `quarkus-picocli`, `picocli-codegen` deps | Replaced by `quarkus-arc` + `aesh` |
| client/pom.xml | Commented-out picocli plugins block | Dead code referencing removed picocli tools |

### Skill Improvement Suggestions
- Add a section on migrating Quarkus picocli applications (`@TopCommand` → `@QuarkusMain` + `AeshRuntimeRunner`)
- Document that Quarkus BOM may override `readline` version, breaking Aesh — include the `dependencyManagement` override pattern
- Note that `@GroupCommandDefinition` lacks `generateHelp` and `version` attributes
- Document the lossy mapping for multiple long option names (picocli allows N, Aesh allows 1)
14:44:00,578 INFO  [AcpClientCommand] [Update] usage_update: UsageUpdate[meta=null, used=131040, size=200000, cost=null]
14:44:00,595 INFO  [AcpClientCommand] [Update] usage_update: UsageUpdate[meta=null, used=131040, size=200000, cost={amount=5.6307765, currency=USD}]
14:44:00,604 INFO  [AcpClientCommand] Done! Stop reason: END_TURN
14:44:00,622 INFO  [StdioAcpClientTransport] ACP agent process stopped (exit code 0)
14:44:00,631 INFO  [quarkus] acp-java-client stopped in 0.008s

[cmoulliard]

Test results using the fPR 13 and commit: 8a0b237

## Phase 5: Migration Report                                                                                                                                                                                     

## Migration Report: acp-java-client

### Summary
- Agent: Claude Code
- Model: claude-opus-4-6
- Modules completed: 4/4 (build, code, testing [skipped - no tests], cleanup)
- Checks passed: 6/6

### Changes by Module

| Module | Files changed | Key changes |
|--------|--------------|-------------|
| build | `pom.xml` (parent), `client/pom.xml`, `client/src/main/resources/application.properties` | Removed `quarkus-picocli` dep, added `quarkus-arc` + `aesh:3.8`, added `readline` override in dependencyManagement to prevent Quarkus BOM conflicts, added `aesh.version` property |
| code | `client/src/main/java/.../AcpAgentCommand.java` (rewritten), `client/src/main/java/.../AcpMain.java` (new) | `@TopCommand` + `@CommandLine.Command` → `@CommandDefinition`; `implements Runnable` → `implements Command<CommandInvocation>`; `void run()` → `CommandResult execute(CommandInvocation)`; 14 `@CommandLine.Option` → Aesh `@Option`; Created `@QuarkusMain` entry point with `AeshRuntimeRunner`; `System.out.println` → `invocation.println` in execute method; `System.exit(1)` → `return CommandResult.FAILURE`; removed `GenerateCompletion` subcommand (Aesh provides `--aesh-completion` automatically) |
| testing | N/A | No test files in client module — skipped |
| cleanup | Verified clean | Zero picocli imports, zero picocli dependencies, no AutoComplete code, no GraalVM reflection config |

### Validation Results

| Check | Result | Notes |
|-------|--------|-------|
| Builds | PASS | `mvn clean package -DskipTests -pl client` succeeds, uber-jar produced |
| No picocli deps | PASS | Zero `info.picocli` references in any pom.xml |
| Has Aesh | PASS | `org.aesh:aesh:3.8` present in client/pom.xml |
| Tests pass | PASS | No tests to run (no test files exist) |
| CLI runs | PASS | `java -jar ... --help` displays correct Aesh-generated help with all options |
| No leftover imports | PASS | Zero `import picocli` in source tree |

### Unmigrated Code (TODOs)

| File | Line | What | Why not migrated |
|------|------|------|-----------------|
| — | — | — | Everything was migrated successfully |

### Removed Code

| File | What was removed | Justification |
|------|-----------------|---------------|
| `AcpAgentCommand.java` | `@TopCommand` annotation | Quarkus picocli-specific; replaced by `@QuarkusMain` in new `AcpMain.java` |
| `AcpAgentCommand.java` | `import picocli.AutoComplete.GenerateCompletion` + `subcommands = GenerateCompletion.class` | Picocli-specific auto-completion subcommand. Aesh provides built-in completion via `--aesh-completion` and `--aesh-completion-install` flags — no extra code needed |
| `AcpAgentCommand.java` | `@CommandLine.Command(version = "0.1.0-SNAPSHOT")` | Aesh `@CommandDefinition` does not have a `version` attribute. The version information is available from Quarkus runtime instead |
| `AcpAgentCommand.java` | `--wks` alias for `--workspace-path` | Aesh only supports one long name per option (`name` attribute). The `--wks` 3-character alias is not a valid `shortName` (must be a single char). Users should use `--workspace-path` instead |
| `AcpAgentCommand.java` | `requestTimeout` and `promptTimeout` changed from `Integer` to `String` | Aesh `@Option` maps to field type directly; using `String` avoids parsing issues and matches the existing `resolveOption` helper pattern |

### Key Design Decisions

1. **`@QuarkusMain` instead of `quarkus-aesh`**: There is no `quarkus-aesh` extension available, so I created a `@QuarkusMain` class (`AcpMain.java`) that uses `AeshRuntimeRunner` to bridge Quarkus lifecycle with Aesh command execution.

2. **`System.out.print` retained in callbacks**: The `handleSessionUpdate` and `handlePermissionRequest` methods run inside event callbacks without access to `CommandInvocation`. Switching these to `invocation.println()` would require storing the invocation as a field and dealing with thread-safety concerns. The `System.out` calls were retained in these callbacks; only the direct output in `execute()` was migrated to `invocation.println()`.

3. **`quarkus-arc` dependency added**: Removing `quarkus-picocli` also removed the transitive Quarkus runtime dependency. Added `quarkus-arc` as the minimal dependency that provides `@QuarkusMain`, CDI, and JBoss logging.

4. **Readline override in dependencyManagement**: Added `org.aesh:readline:${aesh.version}` override in the client's `dependencyManagement` to prevent the Quarkus BOM from pulling an incompatible older version of readline.

### Skill Improvement Suggestions
- The annotation-map should note that `@CommandDefinition` does not have a `version` attribute (unlike picocli's `@Command(version = "...")`)
- The skill should mention that `quarkus-picocli` → Aesh migration requires adding `quarkus-arc` (or similar) since removing `quarkus-picocli` drops the transitive Quarkus runtime dependency
- The `--wks`/multiple-long-name alias loss should be documented as a known Aesh limitation in the annotation map
- The code module should address how to handle `System.out` in event callbacks that don't have access to