fix: upgrade to Spring Shell 4

[arnabnandy7]

Summary

Upgrade the shell module from Spring Shell 3.x to Spring Shell 4.0.2 for Spring Boot 4 compatibility.

Fixes #1720.

Changes

• Manage Spring Shell 4.0.2 at the parent POM level.
• Replace removed legacy annotations:
  • @ShellComponent → @Component
  • @ShellMethod → @Command
  • @ShellOption → @Option
• Preserve existing command names and aliases.
• Migrate options to the Spring Shell 4 shortName and longName attributes.
• Update documentation and custom-command examples to use the Spring Shell 4 API.
• Update the shell starter documentation.

Compatibility notes

Spring Shell 4 only supports a single-character short option name. Consequently:

• -td was removed; use --toolDelay.
• -od was removed; use --operationDelay.
• The conflicting set-options -s alias for showPlanning is now -P, consistent with the execute command.

Verification

• Ran the full mvn clean install reactor build on JDK 21.
• Confirmed all 81 modules build and test successfully.
• Installed the updated 1.5.2-SNAPSHOT locally.
• Launched the Java horoscope example against the updated snapshot.
• Confirmed the application reaches the interactive Spring Shell prompt.
• Confirmed tab completion lists the migrated Embabel commands, including execute.

Result: BUILD SUCCESS with exit code 0.

[igordayen]

@arnabnandy7 looks good, are any tests involed. how to deal with other repos that use extensively legacy annotations?

[arnabnandy7]

@arnabnandy7 looks good, are any tests involed. how to deal with other repos that use extensively legacy annotations?

@igordayen the existing embabel-agent-shell test suite covers the affected shell behavior. I ran:

mvn -pl embabel-agent-shell -DskipITs test

All 56 tests passed with no failures, errors, or skipped tests. The full CI build is also passing.

Repositories using the legacy Spring Shell annotations will need to migrate when upgrading to this version because Spring Shell 4 no longer provides that annotation API. The main mappings are:

• @ShellComponent → Spring @Component
• @ShellMethod → @Command
• @ShellOption → @Option

Command names move to command, descriptions to description, and option aliases are expressed through longNames and single-character shortNames. Multi-character legacy short options need to become long names or be removed as short aliases.

[igordayen]

@arnabnandy7 steps to validate possible breakages:

1. cd embabel-agent
2. mvn clean install (with your code)
3. cd embabel-examples/scripts/java
4. run horoscope example
5. in shell - TAB - to see the list of shell commands (not sure about windows, as im on ubuntu)

if no breakages, then we can plan other repos upgrades, starting with examples

thank you

[urferr]

I guess there is one problem in this change. The first parameter „intent“ of the „execute“ command is annotated with @option but neither shortName nor longName is defined which will not work in my experience. Here the annotation @option seems to be wrong and @argument(index = 0, description = …) to get the same behaviour as before and as described in the the @command annotation.

[arnabnandy7]

if no breakages, then we can plan other repos upgrades, starting with examples

Thanks, @igordayen . I followed your suggested validation flow and also checked the downstream repositories you mentioned.

First, I built the changes from embabel-agent#1956 and installed the updated 1.5.2-SNAPSHOT locally. I then ran the complete mvn clean install build on JDK 21, matching the repository’s CI configuration. All 81 modules built and tested successfully, with BUILD SUCCESS and exit code 0.

I ran the Java horoscope example from embabel-agent-examples/scripts/java against the local snapshot. The application reached the interactive shell prompt, and tab completion showed the migrated commands, including execute, goals, models, platform, and runs.

Testing the downstream repositories exposed some Spring Shell 3/4 compatibility issues, so I prepared the necessary updates:

• Examples: embabel-agent-examples#138, tracked by #137. This removes the mixed Spring Shell dependency graph and migrates the example commands while preserving their existing names. Dependency resolution, compilation, interactive startup, command discovery, and tab completion were verified.

• Prepper: prepper#2, tracked by #3. Its shell commands and affected Agent API usage were migrated. Dependency resolution, compilation, and tests were verified.

• Agent Gen: agent-gen#10, tracked by #9. Its commands and filename completion were migrated to Spring Shell 4. Dependency resolution, compilation, and focused command tests passed. The remaining live integration tests require external credentials, but no Spring Shell compatibility failures were found.

I’ve attached the consolidated validation log. Based on the checks you requested, the Spring Shell upgrade and downstream command registration have now been validated.

[arnabnandy7]

I guess there is one problem in this change. The first parameter „intent“ of the „execute“ command is annotated with @option but neither shortName nor longName is defined which will not work in my experience. Here the annotation @option seems to be wrong and @argument(index = 0, description = …) to get the same behaviour as before and as described in the the @command annotation.

@urferr thanks for catching this. I updated execute to use @Argument(index = 0) for its positional intent. I also corrected the same positional pattern in chooseGoal and setContext.

The focused shell module tests pass, and I verified that the compiled command metadata contains @Argument(index = 0) for all three parameters. The existing named flags remain @Option.

[igordayen]

@arnabnandy7 - thanks for validation on other repos as well. good news - changes on embabel-agent does not affect other repos upon switching to local 1.5.2-snapshot, so new /old shell commands can coexist. regards