# shellcheck shell=sh
# Capability probes against the spt CLI, with the positive control that makes their answers
# trustworthy. [impl->REQ-HAZARD-VERSION-GATE-FAIL-CLOSED]
#
# WHY THIS EXISTS. Ints capability-detect rather than version-parse, which is right — but the naive
# form, `spt <verb> --help | grep -q -- '--flag'`, cannot tell three different worlds apart:
#   (1) the verb exists and lacks the flag   -> a genuine capability gap; SKIP is honest
#   (2) the verb exists and has the flag     -> proceed
#   (3) the verb REFUSED or does not exist   -> the probe learned NOTHING
# Case (3) produces the same empty grep as case (1). Reading it as (1) is what made
# multi-subnet-bringup-int.sh exit 0 announcing it skipped for being too OLD on spt-core 0.54.0 —
# the exact version it existed to test — after `endpoint run` was retired out from under it.
#
# So a probe must FIRST prove it read a real `--help` body (exit 0 AND a `usage` line: the positive
# control that must match) before any zero-match is allowed to mean "feature absent". Callers get
# case (3) as its own return code and MUST fail on it, never skip: a skip is a verdict — "not
# applicable" — and a gate may not assert more than it measured.

# sptc_flag_supported <flag> <cmd> [args...]
#   rc 0 — the command answered AND advertises <flag>
#   rc 1 — the command answered and does NOT advertise it (a real capability gap; SKIP is honest)
#   rc 2 — THE PROBE FAILED. The command did not answer, so nothing is known about the flag.
#          Callers MUST NOT read this as "feature absent" — it is equally "feature moved".
sptc_flag_supported() {
  _flag=$1; shift
  _out=$("$@" --help 2>&1); _prc=$?
  if [ "$_prc" -ne 0 ] || ! printf '%s' "$_out" | grep -qi 'usage'; then
    return 2
  fi
  if printf '%s' "$_out" | grep -q -- "$_flag"; then return 0; fi
  return 1
}