#!/usr/bin/env bash
#
# One attempt per release, enforced by the filesystem.
#
# A watcher loop asks this before it spawns anything. Exit 0 means "you have the claim, go". Exit 1 means
# "somebody already had it" — and that answer never changes back, whatever happened to the attempt that
# held it. A release that fails is not retried; it is looked at.
#
# WHY THIS IS A SCRIPT AND NOT A PARAGRAPH IN prompts/deploy-commander.md
#
# The watcher loop is written fresh by an agent each time it arms, so a rule that lives only in prose is
# re-implemented from scratch on every arming, and "skip a version already attempted" has a wrong version
# that looks right: test the .done file, which only exists on SUCCESS. Write that and a failing deploy
# spawns a fresh agent every poll, all night, each one costing money. That is exactly what happened on
# 2026-08-21 — the loop was careful, logged honestly, and still had an unbounded retry in it.
#
# WHY BASH AND NOT bun
#
# The thing that stops a retry storm must not depend on the checkout being healthy. A deploy that dies on
# `bun install` is precisely when this has to work.
#
# WHY mkdir
#
# It is atomic on every POSIX filesystem and it fails if the target exists — one syscall that both tests
# and claims. `[ -f x ] && ...` is two steps with a race between them, and two pollers a second apart is
# not a hypothetical when a watcher is restarted.
set -u

DEPLOYS_DIR="${DEPLOYS_DIR:-$HOME/officer-dev/data/deploys}"

usage() {
  cat >&2 <<'USAGE'
usage: deploy-claim.sh claim <version>    take the one attempt for this release (exit 0 = yours, 1 = taken)
       deploy-claim.sh done  <version>    record that the attempt succeeded
       deploy-claim.sh state <version>    print unclaimed | claimed | done
       deploy-claim.sh list               every release this host knows about

To retry a release deliberately: rm -rf <deploys-dir>/<version>.claim
That is a human act on purpose. A loop cannot undo its own claim.
USAGE
  exit 2
}

version_ok() {
  # The version reaches here from a git tag, so it is attacker-adjacent input used to build a path.
  case "$1" in
    *[!0-9.]* | '' | *..*) return 1 ;;
    *) return 0 ;;
  esac
}

CMD="${1:-}"
[ -n "$CMD" ] || usage

case "$CMD" in
  list)
    mkdir -p "$DEPLOYS_DIR"
    found=0
    for d in "$DEPLOYS_DIR"/*.claim; do
      [ -e "$d" ] || continue
      found=1
      v=$(basename "$d" .claim)
      if [ -f "$DEPLOYS_DIR/$v.done" ]; then s="done"; else s="claimed, no success recorded"; fi
      printf '%-16s %s\n' "$v" "$s"
    done
    [ "$found" = 1 ] || echo "no releases attempted on this host"
    ;;

  claim | done | state)
    V="${2:-}"
    [ -n "$V" ] || usage
    version_ok "$V" || { echo "deploy-claim: refusing a version that is not digits and dots: $V" >&2; exit 2; }
    mkdir -p "$DEPLOYS_DIR" || exit 2
    CLAIM="$DEPLOYS_DIR/$V.claim"
    DONE="$DEPLOYS_DIR/$V.done"

    case "$CMD" in
      state)
        if [ -f "$DONE" ]; then echo done
        elif [ -d "$CLAIM" ]; then echo claimed
        else echo unclaimed; fi
        ;;
      claim)
        # A pre-existing .done with no .claim is a release deployed before this script existed. Honour it.
        if [ -f "$DONE" ]; then
          echo "deploy-claim: $V is already deployed" >&2
          exit 1
        fi
        if mkdir "$CLAIM" 2>/dev/null; then
          printf '%s claimed on %s by pid %s\n' "$(date -Iseconds)" "$(hostname)" "$$" > "$CLAIM/by"
          echo "deploy-claim: $V is yours"
          exit 0
        fi
        printf 'deploy-claim: %s was already attempted — %s\n' "$V" "$(cat "$CLAIM/by" 2>/dev/null || echo 'claim exists')" >&2
        echo "deploy-claim: NOT retrying. Look at what failed, then rm -rf $CLAIM to allow another attempt." >&2
        exit 1
        ;;
      done)
        [ -d "$CLAIM" ] || echo "deploy-claim: warning — recording success for $V that was never claimed" >&2
        printf '%s succeeded on %s\n' "$(date -Iseconds)" "$(hostname)" >> "$DONE"
        echo "deploy-claim: $V recorded as deployed"
        ;;
    esac
    ;;

  *) usage ;;
esac