# shellcheck shell=sh
# One place that knows how spt spells "bring an endpoint up", across the spt-core 0.54.0 lifecycle
# rename. Sourced by the ints whose bringup is a MEANS to their test, not the thing under test.
#
# REQUIRES ci/lib/spt-probe.sh — source it FIRST. The shape detection below must distinguish
# "endpoint run exists" from "endpoint run refused", and that positive control lives in exactly one
# place rather than being copied per caller. Not self-sourced on purpose: inside a sourced file `$0`
# names the CALLER, so a relative source here resolves against whichever int pulled us in.
#
# 0.54.0 retired `spt endpoint run` with no aliases and split it into one verb per step. The tokens
# did NOT move with the verb: `ENDPOINT_RUN_STARTED:<id>` is still the machine token for "a session
# started", and the ENDPOINT_RUN_FAIL:/_NOT_HARNESS:/_ADAPTER_UNREGISTERED:/_DAEMON_FAIL:/
# _SESSION_TIMEOUT:/_NOT_MEMBER: family all survive under their old spellings — so a caller's
# confirm-match needs no change. `create` adds one NEW token of its own, `ENDPOINT_CREATED:<id>
# adapter=<a>`, because create starts no session and must not claim it did.
# (Contract per deployah, read off the v0.54.0 tag = 86f0d84: argv from the clap definitions, tokens
# from their emit sites.)
#
# ⚠️ THE create-start BRANCH IS AUTHORED, NOT YET EXERCISED. Every node in this fleet still runs
# < 0.54.0, so only the `run` branch executes today and it is byte-for-byte the previous behaviour.
# The create-start branch is re-verified on a real 0.54.0 daemon before it is trusted —
# docs/plans/CORE-054-MIGRATION-PLAN.md holds that debt.

# sptc_bringup_shape — which lifecycle contract is this node running?
# Echoes `run` | `create-start` | `unknown`. Returns 1 only for `unknown`.
#
# FAILS CLOSED BY CONSTRUCTION (REQ-HAZARD-VERSION-GATE-FAIL-CLOSED). `endpoint run --help` is only
# believed when it EXITS 0 AND carries a `usage` body — the positive control. A refusing command
# yields an empty grep that is byte-indistinguishable from a feature that was never there, and
# reading that as "old build" is what made the multi-subnet suite pass by skipping on the exact
# version it existed to test. An unreadable instrument is `unknown`, never a version verdict.
# [impl->REQ-HAZARD-VERSION-GATE-FAIL-CLOSED]
sptc_bringup_shape() {
  # `--adapter` is just a flag `endpoint run` has always carried — it is the ANSWERING of the probe
  # that matters here, not the flag. rc 0 or 1 both mean the verb replied with a real --help body, so
  # `endpoint run` exists; rc 2 means it did not answer and nothing is known.
  sptc_flag_supported '--adapter' spt endpoint run
  case $? in
    0|1) echo run; return 0 ;;
  esac
  if spt endpoint create --help >/dev/null 2>&1; then
    echo create-start; return 0
  fi
  echo unknown; return 1
}

# sptc_bringup <id> <adapter> <cwd> [subnet]
# Brings an endpoint up on whichever contract this node runs, and echoes the combined output so the
# caller can confirm-match `ENDPOINT_RUN_STARTED:<id>` exactly as it always has.
sptc_bringup() {
  _id=$1; _a=$2; _bcwd=$3; _sub=$4
  case "$(sptc_bringup_shape)" in
    run)
      # Pre-0.54.0: one command, and it takes the cwd from the shell.
      if [ -n "$_sub" ]; then
        ( cd "$_bcwd" && spt endpoint run --adapter "$_a" --id "$_id" --start --subnet "$_sub" 2>&1 )
      else
        ( cd "$_bcwd" && spt endpoint run --adapter "$_a" --id "$_id" --start 2>&1 )
      fi
      ;;
    create-start)
      # 0.54.0+: mint, then start. THE CWD IS PASSED EXPLICITLY AND DELIBERATELY — `start` "lands on
      # the endpoint's most-recent adapter in its most-recent project folder, never on the folder you
      # happen to be standing in", so a subshell `cd` silently stops carrying and the probe lands
      # somewhere the caller did not intend, failing as though bringup were broken.
      # `--subnet` is CREATE-ONLY and required on a multi-subnet node: the home is assigned at
      # creation and is permanent, so the later verbs refuse it rather than appear to re-home.
      if [ -n "$_sub" ]; then
        spt endpoint create "$_id" --adapter "$_a" --cwd "$_bcwd" --subnet "$_sub" 2>&1
      else
        spt endpoint create "$_id" --adapter "$_a" --cwd "$_bcwd" 2>&1
      fi
      spt endpoint start "$_id" 2>&1
      ;;
    *)
      echo "SPTC_BRINGUP_SHAPE_UNKNOWN: 'spt endpoint run --help' did not answer and 'spt endpoint create' is absent" >&2
      return 1
      ;;
  esac
}