[
https://issues.apache.org/jira/browse/CAMEL-25389?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18127560#comment-18127560
]
Claus Ibsen commented on CAMEL-25389:
-------------------------------------
PR: https://github.com/apache/camel/pull/27909
Done as described above, with two changes after a best-practice review of exit
codes (other CLIs, POSIX shells, sysexits.h, picocli, JBang's own codes, and
what AI agents act on):
* *Timeout is 124, not 4.* 124 is the code of GNU {{timeout}}, so models and
scripts already read it as a timeout, and 4 is JBang's own "internal error"
exit code. The semantic commands (4.23.0) used 4 and now use 124; the 4.24
upgrade guide says so.
* *{{CAMEL_CLI_DEBUG=true}}, not {{CAMEL_DEBUG}},* prints the stack trace of
every error ({{--verbose}} does the same). {{CAMEL_DEBUG}} reads like the
{{camel debug}} command or the {{camel.debug.*}} options.
So the contract is: 0 success, 1 failed, 2 usage error, 3 not found, 70
internal error, 124 timed out. Codes from 126 up are left to the shell and
signals (130 Ctrl+C, 137 SIGKILL, 143 SIGTERM). {{camel --help}} lists the
codes, and the new docs page "Camel CLI - Exit Codes and Output"
({{camel-jbang-exit-codes.adoc}}) explains them.
Also in the PR: an {{Error}} that escapes picocli exits 70; a missing file
({{NoSuchFileException}}, {{FileNotFoundException}}, {{ResourceDoesNotExist}})
exits 3; the first use of a plugin command installs the plugin and runs the
command; the legacy settings migration notice goes to stderr (it runs before
every command and could break JSON on stdout); {{camel run}} returns 0
explicitly when stopped from outside.
Not done here: PR 27715 is still open, so moving its "parser could not work out
these parts" note to the stderr channel happens in whichever of the two lands
second.
_Claude Code on behalf of davsclaus (Claus Ibsen)_
> camel-jbang - Exit code contract, stderr for errors, central error handling
> ---------------------------------------------------------------------------
>
> Key: CAMEL-25389
> URL: https://issues.apache.org/jira/browse/CAMEL-25389
> Project: Camel
> Issue Type: Sub-task
> Components: camel-jbang
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.24.0
>
>
> * Add {{CliExitCode}} constants (0,1,2,3,4,70) and {{CliException(code,
> message)}}.
> * Install a picocli execution-exception handler and exit-code mapper in
> {{CamelJBangMain}}: {{CliException}} prints one {{ERROR:}} line on stderr;
> other exceptions exit 70 with stack trace on stderr; stack traces for 1/3/4
> only with {{CAMEL_DEBUG=true}}/{{--verbose}}.
> * {{Printer}} gets an error channel ({{printErr}}, {{printWarn}},
> {{printTip}}) that goes to stderr; {{StringPrinter}} captures stdout and
> stderr separately.
> * Move the ~25 {{println("Error: ...")}} sites to {{printErr}}, and non-error
> text out of {{printErr}} (e.g. {{transform dataweave}} summary).
> * "Plugins (not installed)" banner: stderr, and suppressed without a TTY.
> * Unknown command matching a plugin name must not exit 0 after
> auto-installing.
> * Parent commands ({{transform}}, {{eval}}, {{catalog}}, {{cmd}}, {{config}},
> {{infra}}, {{plugin}}, {{update}}, {{version}}, {{dependency}}) use their own
> {{CommandLine}} so help lists subcommands and the child's exit code
> propagates.
> * Replace {{return -1}} (exit 255) with proper codes.
> * New docs page "Exit codes and machine-readable output"; create
> {{camel-4x-upgrade-guide-4_24.adoc}} entry.
> _Claude Code on behalf of davsclaus (Claus Ibsen)_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
