feat: version-skew nudge — stamp store writer-version, warn when behind (EGB-713)

test/version.bats

@@ -0,0 +1,106 @@
+#!/usr/bin/env bats
+# EGB-713 version-skew nudge: writer-version stamp, numeric comparator, skew
+# warning, `which` surface. bash 3.2: every standalone [[ ]] ends with || false.
+
+load test_helper
+
+VERSION_FILE() { echo "$(cd "$(dirname "$SECRETS_BIN")" && pwd)/VERSION"; }
+
+# ─── comparator contract ──────────────────────────────────────────────
+
+@test "version comparator orders 0.7.0.0 < 0.10.0.0 numerically (not lexically)" {
+  run bash -c '
+    _version_gt() {
+      local a="$1" b="$2" i ai bi; local -a af bf
+      IFS=. read -r -a af <<< "$a"; IFS=. read -r -a bf <<< "$b"
+      for i in 0 1 2 3; do
+        ai=${af[$i]:-0}; ai=${ai//[!0-9]/}; [ -n "$ai" ] || ai=0
+        bi=${bf[$i]:-0}; bi=${bi//[!0-9]/}; [ -n "$bi" ] || bi=0
+        if [ "$((10#$ai))" -gt "$((10#$bi))" ]; then return 0; fi
+        if [ "$((10#$ai))" -lt "$((10#$bi))" ]; then return 1; fi
+      done; return 1
+    }
+    _version_gt 0.10.0.0 0.7.0.0 && echo "10gt7"
+    _version_gt 0.7.0.0 0.10.0.0 || echo "7not_gt_10"
+    _version_gt 0.7.0.0 0.7.0.0 || echo "equal_not_gt"
+    _version_gt 1.0.0.0 0.9.9.9 && echo "major_wins"
+  '
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"10gt7"* ]] || false
+  [[ "$output" == *"7not_gt_10"* ]] || false
+  [[ "$output" == *"equal_not_gt"* ]] || false
+  [[ "$output" == *"major_wins"* ]] || false
+}
+
+# ─── stamp on write ───────────────────────────────────────────────────
+
+@test "push stamps the store writer-version with the client version" {
+  init_with_remote
+  create_project_dir wvstamp
+  "$SECRETS_BIN" push wvstamp >/dev/null 2>&1
+  [ -f "$SECRETS_DIR/.secrets-writer-version" ]
+  run cat "$SECRETS_DIR/.secrets-writer-version"
+  [ "$output" = "$(cat "$(VERSION_FILE)")" ]
+}
+
+@test "writer-version stamp is monotonic (a push never lowers a higher stamp)" {
+  init_with_remote
+  create_project_dir wvmono
+  printf '9.9.9.9\n' > "$SECRETS_DIR/.secrets-writer-version"
+  "$SECRETS_BIN" push wvmono >/dev/null 2>&1
+  run cat "$SECRETS_DIR/.secrets-writer-version"
+  [ "$output" = "9.9.9.9" ]
+}
+
+@test "writer-version stamp is committed, not gitignored" {
+  init_with_remote
+  create_project_dir wvcommit
+  "$SECRETS_BIN" push wvcommit >/dev/null 2>&1
+  run bash -c "git -C $SECRETS_DIR ls-files | grep -qx .secrets-writer-version"
+  [ "$status" -eq 0 ]
+}
+
+# ─── skew warning on command ──────────────────────────────────────────
+
+@test "a store written by a newer version warns on a command (non-fatal)" {
+  init_with_remote
+  create_project_dir skewwarn
+  "$SECRETS_BIN" push skewwarn >/dev/null 2>&1
+  printf '99.0.0.0\n' > "$SECRETS_DIR/.secrets-writer-version"
+  run "$SECRETS_BIN" list
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"last written by secrets v99.0.0.0"* ]] || false
+  [[ "$output" == *"Update your secrets tool"* ]] || false
+}
+
+@test "a store at the same/older version is silent" {
+  init_with_remote
+  create_project_dir noskew
+  "$SECRETS_BIN" push noskew >/dev/null 2>&1
+  run "$SECRETS_BIN" list
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"Update your secrets tool"* ]] || false
+}
+
+@test "a store with no writer-version marker is silent (legacy store)" {
+  init_with_remote
+  create_project_dir legacynostamp
+  "$SECRETS_BIN" push legacynostamp >/dev/null 2>&1
+  rm -f "$SECRETS_DIR/.secrets-writer-version"
+  run "$SECRETS_BIN" list
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"Update your secrets tool"* ]] || false
+}
+
+# ─── which surface ────────────────────────────────────────────────────
+
+@test "which prints the store writer-version and a behind note" {
+  init_with_remote
+  create_project_dir whichwv
+  "$SECRETS_BIN" push whichwv >/dev/null 2>&1
+  printf '99.0.0.0\n' > "$SECRETS_DIR/.secrets-writer-version"
+  run "$SECRETS_BIN" which
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"written-by: v99.0.0.0"* ]] || false
+  [[ "$output" == *"behind"* ]] || false
+}