feat(cli): add entrypoint with --help/--version and exit codes

tests/run.sh

@@ -48,6 +48,88 @@ else
     fail "--version exited non-zero (rc=$rc): $version_out"
 fi
 
+# --- 3. --help must exit 0 and print usage on stdout ----------------------
+help_out=
+help_rc=0
+help_out=$("$BIN" --help 2>/dev/null) || help_rc=$?
+if [ "$help_rc" -eq 0 ]; then
+    case "$help_out" in
+    *"Usage: "*)
+        pass "--help exits 0 and prints usage on stdout" ;;
+    *)
+        fail "--help printed no usage on stdout: '$help_out'" ;;
+    esac
+else
+    fail "--help exited non-zero (rc=$help_rc): $help_out"
+fi
+
+# --- 4. unknown option must exit 2, usage on stderr, silent stdout -------
+bogus_out=
+bogus_rc=0
+bogus_out=$("$BIN" --bogus 2>&1 >/dev/null) || bogus_rc=$?
+if [ "$bogus_rc" -eq 2 ]; then
+    case "$bogus_out" in
+    *"Usage: "*)
+        pass "--bogus exits 2 and prints usage on stderr" ;;
+    *)
+        fail "--bogus printed no usage on stderr: '$bogus_out'" ;;
+    esac
+else
+    fail "--bogus exited rc=$bogus_rc (want 2): $bogus_out"
+fi
+if [ -z "$("$BIN" --bogus 2>/dev/null)" ]; then
+    pass "--bogus prints nothing on stdout"
+else
+    fail "--bogus leaked output on stdout"
+fi
+
+# --- 5. no arguments must exit 1 with usage on stderr ---------------------
+noargs_out=
+noargs_rc=0
+noargs_out=$("$BIN" 2>&1 >/dev/null) || noargs_rc=$?
+if [ "$noargs_rc" -eq 1 ]; then
+    case "$noargs_out" in
+    *"Usage: "*)
+        pass "no arguments exits 1 and prints usage on stderr" ;;
+    *)
+        fail "no arguments printed no usage on stderr: '$noargs_out'" ;;
+    esac
+else
+    fail "no arguments exited rc=$noargs_rc (want 1): $noargs_out"
+fi
+
+# --- 6. one positional buildfile must be accepted (exit 0, no read) ------
+if "$BIN" buildfile.kdl >/dev/null 2>&1; then
+    pass "one positional buildfile is accepted (exit 0)"
+else
+    fail "one positional buildfile was rejected (rc=$?)"
+fi
+
+# --- 7. --version=1 is an unknown option form -> exit 2 -------------------
+"$BIN" --version=1 >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 2 ]; then
+    pass "--version=1 exits 2 (unknown option)"
+else
+    fail "--version=1 exited rc=$rc (want 2)"
+fi
+
+# --- 8. -- ends option parsing; following text is positional --------------
+if "$BIN" -- --bogus >/dev/null 2>&1; then
+    pass "-- terminates option parsing (--bogus taken as buildfile)"
+else
+    fail "-- --bogus exited non-zero (rc=$?)"
+fi
+
+# --- 9. two positionals are a usage error -> exit 2 -----------------------
+"$BIN" a.kdl b.kdl >/dev/null 2>&1
+rc=$?
+if [ "$rc" -eq 2 ]; then
+    pass "two positionals exit 2 (usage error)"
+else
+    fail "two positionals exited rc=$rc (want 2)"
+fi
+
 # --- summary -------------------------------------------------------------
 if [ "$TESTS_FAILED" -ne 0 ]; then
     printf 'FAILED: %d/%d checks failed\n' "$TESTS_FAILED" "$TESTS_RUN" >&2