feat(isthmus-cli): explain common SQL conversion errors instead of dumping stack traces

[nielspardon]

isthmus "SELECT * FROM foo" answered a beginner's first attempt with a 40-line CalciteContextException stack trace that never mentioned -c / --create. Every other way to get the input wrong behaved the same way, up to an outright NullPointerException when no query was passed at all.

$ isthmus "SELECT * FROM foo"
Error: From line 1, column 15 to line 1, column 17: Object 'FOO' not found

Hint: table definitions are not part of the query. Pass a CREATE TABLE
statement for each table it references using -c / --create:

  isthmus -c "CREATE TABLE FOO (col1 INT, col2 VARCHAR)" "SELECT * FROM FOO"

Unquoted identifiers are upper-cased unless --unquotedcasing says otherwise.

What changes

• Failures caused by the input are reported as a message, with a hint naming the option to reach for wherever the mistake is identifiable: an undefined table points at -c / --create (with its own name in the example), an unresolved column or an unresolved identifier in -e / --expression explains where columns come from and mentions --unquotedcasing, and a CREATE TABLE given as the query — or a query given to -c — points at the other one.
• Anything that is not recognizably an input problem keeps its stack trace, so defects still reach bug reports intact. The new --stacktrace prints the message and the full trace for the recognized failures.
• Missing input is a usage error. With neither a query nor -e the CLI threw a NullPointerException; it now prints Missing SQL to convert plus the usage. Relatedly, main no longer parses arguments ahead of execute(), so an unquoted or mistyped argument gets picocli's usage error rather than an UnmatchedArgumentException trace. Both exit 2, picocli's invalid-input code, where the uncaught exceptions previously exited 1.
• Guards processCreateStatementsToSchema against CTAS, as its sibling processCreateStatements already did. Without the guard, -c "CREATE TABLE foo AS SELECT 1" dereferenced a null column list — a parameter declared @NonNull — and failed with an NPE instead of CTAS not supported.

The --help block in the isthmus-cli readme reflows beyond the added line because the new option widens picocli's option column.

Closes #113

🤖 Generated with AI