devpods.sh

#!/usr/bin/env bash
# =============================================================================
#  devpods — local dev infrastructure via Podman pods
#  Gist: https://gist.github.com/<you>/devpods.sh
#
#  Usage (one-liner):
#    curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- up pg
#    curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- down all
#    curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- status
#    curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- reset mongo
#
#  Subcommands:  up [pod|all]   down [pod|all]   status   reset [pod|all]
#  Pod aliases:  pg  mongo  redis  mail  seq  rmq  nats  (or "all")
#
#  Data lives in: ~/.devpods/<pod-name>/
# =============================================================================
set -euo pipefail
IFS=$'\n\t'

# ─── version ─────────────────────────────────────────────────────────────────
DEVPODS_VERSION="1.5.1"

# ─── colour palette ──────────────────────────────────────────────────────────
if [[ -t 1 ]]; then
  C_RED='\033[0;31m'    C_GRN='\033[0;32m'    C_YLW='\033[1;33m'
  C_BLU='\033[0;34m'    C_CYN='\033[0;36m'    C_MAG='\033[0;35m'
  C_GRY='\033[0;90m'    C_WHT='\033[1;37m'     C_RST='\033[0m'
  C_BLD='\033[1m'
else
  C_RED='' C_GRN='' C_YLW='' C_BLU='' C_CYN='' C_MAG='' C_GRY='' C_WHT='' C_RST='' C_BLD=''
fi

# ─── logging helpers ─────────────────────────────────────────────────────────
banner() { echo -e "\n${C_BLD}${C_CYN}╔══════════════════════════════════════════╗${C_RST}"; \
           printf "${C_BLD}${C_CYN}║${C_RST}  %-42s${C_BLD}${C_CYN}║${C_RST}\n" "$*"; \
           echo -e "${C_BLD}${C_CYN}╚══════════════════════════════════════════╝${C_RST}"; }
info()   { echo -e "  ${C_BLU}→${C_RST}  $*"; }
ok()     { echo -e "  ${C_GRN}✔${C_RST}  $*"; }
warn()   { echo -e "  ${C_YLW}⚠${C_RST}  $*"; }
err()    { echo -e "  ${C_RED}✖${C_RST}  $*" >&2; }
die()    { err "$*"; exit 1; }
section(){ echo -e "\n${C_MAG}▸ $*${C_RST}"; }
dim()    { echo -e "  ${C_GRY}$*${C_RST}"; }

# ─── data root ───────────────────────────────────────────────────────────────
DATA_ROOT="${HOME}/.devpods"

# ─── pod definitions (name => port mappings) ─────────────────────────────────
# Format: "host:container ..."
declare -A POD_PORTS=(
  [dev-pg-pod]="5432:5432 8081:8081"
  [dev-mongo-pod]="27017:27017 8082:8081"
  [dev-redis-pod]="6379:6379 8083:5540"
  [dev-mail-pod]="1025:1025 8025:8025"
  [dev-seq-pod]="5341:80"
  [dev-rmq-pod]="5672:5672 15672:15672"
  [dev-nats-pod]="4222:4222 8222:8222 6222:6222"
  [dev-sms-pod]="4000:4000 5153:5153"
  [dev-minio-pod]="9000:9000 9001:9001"
)

# alias → pod name
declare -A ALIAS_MAP=(
  [pg]=dev-pg-pod   [postgres]=dev-pg-pod
  [mongo]=dev-mongo-pod  [mongodb]=dev-mongo-pod
  [redis]=dev-redis-pod
  [mail]=dev-mail-pod    [mailpit]=dev-mail-pod
  [seq]=dev-seq-pod
  [rmq]=dev-rmq-pod      [rabbitmq]=dev-rmq-pod
  [nats]=dev-nats-pod
  [sms]=dev-sms-pod      [devsms]=dev-sms-pod
  [minio]=dev-minio-pod
)

ALL_PODS=(dev-pg-pod dev-mongo-pod dev-redis-pod dev-mail-pod dev-seq-pod dev-rmq-pod dev-nats-pod dev-sms-pod dev-minio-pod)

# ─── env / credentials (override via ~/.devpods/.env) ────────────────────────
_load_env() {
  [[ -f "${DATA_ROOT}/.env" ]] && source "${DATA_ROOT}/.env"
  PG_USER="${PG_USER:-devuser}"
  PG_PASS="${PG_PASS:-devpass}"
  PG_DB="${PG_DB:-devdb}"
  REDIS_PASS="${REDIS_PASS:-devredis}"
  RMQ_USER="${RMQ_USER:-devuser}"
  RMQ_PASS="${RMQ_PASS:-devpass}"
  MONGO_RS="${MONGO_RS:-rs0}"
  ME_USER="${ME_USER:-admin}"
  ME_PASS="${ME_PASS:-admin}"
  MINIO_ROOT_USER="${MINIO_ROOT_USER:-devminio}"
  MINIO_ROOT_PASS="${MINIO_ROOT_PASS:-devminio123}"
  MINIO_BUCKET="${MINIO_BUCKET:-devsms}"
}

# ─── system readiness checks ──────────────────────────────────────────────────
_check_system() {
  section "System readiness"

  # OS detection
  local os; os="$(uname -s)"
  case "${os}" in
    Linux)  ok "OS: Linux" ;;
    Darwin) ok "OS: macOS" ;;
    *)      die "Unsupported OS: ${os}" ;;
  esac

  # macOS: podman machine must be running
  if [[ "${os}" == "Darwin" ]]; then
    if ! podman machine list 2>/dev/null | grep -q "Currently running"; then
      warn "No running Podman machine found — attempting to start …"
      if podman machine list 2>/dev/null | grep -q "dev\|podman-machine-default"; then
        podman machine start 2>/dev/null || die "Failed to start Podman machine. Run: podman machine init && podman machine start"
        ok "Podman machine started."
      else
        warn "No Podman machine exists. Initialising a default one …"
        podman machine init --cpus 4 --memory 4096 --disk-size 60 2>/dev/null \
          && podman machine start \
          || die "Could not init/start Podman machine. Please run it manually."
        ok "Podman machine initialised and started."
      fi
    else
      ok "Podman machine: running"
    fi
  fi

  # Podman binary
  if ! command -v podman &>/dev/null; then
    die "Podman not found. Install it: https://podman.io/docs/installation"
  fi

  local pv; pv="$(podman --version | awk '{print $3}')"
  local pmaj; pmaj="$(echo "${pv}" | cut -d. -f1)"
  if [[ "${pmaj}" -lt 4 ]]; then
    die "Podman >= 4.0 required (found ${pv}). Please upgrade."
  fi
  ok "Podman ${pv}"

  # socket / service (Linux rootless)
  if [[ "${os}" == "Linux" ]]; then
    if ! podman info &>/dev/null; then
      warn "Podman socket not responding — trying to start user service …"
      systemctl --user start podman.socket 2>/dev/null \
        || warn "Could not start podman.socket (may not be needed on this distro)."
    fi
    ok "Podman daemon: responding"
  fi

  # Data root
  mkdir -p "${DATA_ROOT}"
  ok "Data root: ${DATA_ROOT}"

  # Write sample .env if missing
  if [[ ! -f "${DATA_ROOT}/.env" ]]; then
    cat > "${DATA_ROOT}/.env" <<'ENV'
# devpods credentials — edit freely
PG_USER=devuser
PG_PASS=devpass
PG_DB=devdb
REDIS_PASS=devredis
RMQ_USER=devuser
RMQ_PASS=devpass
MONGO_RS=rs0
ME_USER=admin
ME_PASS=admin
MINIO_ROOT_USER=devminio
MINIO_ROOT_PASS=devminio123
MINIO_BUCKET=devsms
ENV
    ok "Created ${DATA_ROOT}/.env (defaults)"
  fi

  # Registry auth detection — runs once, informs all subsequent pulls
  _detect_registry_auth
}

# ─── pod lifecycle helpers ────────────────────────────────────────────────────
_pod_exists()   { podman pod exists "$1" 2>/dev/null; }
_pod_running()  { [[ "$(podman pod inspect "$1" --format '{{.State}}' 2>/dev/null)" == "Running" ]]; }

_ensure_pod() {
  local pod="$1"; shift
  local ports=("$@")
  if _pod_exists "${pod}"; then
    if _pod_running "${pod}"; then
      warn "Pod ${C_BLD}${pod}${C_RST}${C_YLW} already running — skipping creation."; return 0
    else
      info "Pod ${pod} exists but is not running — removing stale pod …"
      podman pod rm -f "${pod}" >/dev/null 2>&1
    fi
  fi
  local pub_args=()
  for p in "${ports[@]}"; do pub_args+=("--publish" "${p}"); done
  podman pod create --name "${pod}" "${pub_args[@]}" >/dev/null
}

_wait_healthy() {
  local container="$1" retries="${2:-30}" delay="${3:-2}"
  local i=0
  while (( i < retries )); do
    local state; state="$(podman inspect --format '{{.State.Health.Status}}' "${container}" 2>/dev/null || true)"
    [[ "${state}" == "healthy" ]] && return 0
    # fallback: just check running
    state="$(podman inspect --format '{{.State.Status}}' "${container}" 2>/dev/null || true)"
    [[ "${state}" == "running" ]] && return 0
    sleep "${delay}"; (( i++ ))
  done
  warn "Container ${container} did not become healthy in time — continuing anyway."
}

_stop_pod() {
  local pod="$1"
  if _pod_exists "${pod}"; then
    info "Stopping pod ${C_BLD}${pod}${C_RST} …"
    podman pod stop "${pod}" >/dev/null 2>&1 || true
    podman pod rm   "${pod}" >/dev/null 2>&1 || true
    ok "Removed ${pod}"
  else
    dim "Pod ${pod} not found — nothing to do."
  fi
}

_reset_pod() {
  local pod="$1"
  local data_dir="${DATA_ROOT}/${pod}"
  _stop_pod "${pod}"
  if [[ -d "${data_dir}" ]]; then
    warn "Deleting data at ${data_dir} …"
    rm -rf "${data_dir}"
    ok "Data cleared for ${pod}"
  fi
}

# ─── registry / mirror resolution ────────────────────────────────────────────
# Detect whether we are authenticated to docker.io.
# Sets global DOCKER_AUTHED=1 if logged in, 0 otherwise.
# Also builds PULL_CANDIDATES: ordered list of registries to try for a given
# docker.io image — authed hub first, then mirror.gcr.io as silent fallback.
_detect_registry_auth() {
  DOCKER_AUTHED=0
  # podman login --get-login exits 0 and prints username when authed
  if podman login --get-login docker.io &>/dev/null; then
    DOCKER_AUTHED=1
    local hub_user; hub_user="$(podman login --get-login docker.io 2>/dev/null)"
    ok "Docker Hub: authenticated as ${C_BLD}${hub_user}${C_RST}"
  else
    warn "Docker Hub: not authenticated — will use ${C_BLD}mirror.gcr.io${C_RST} as primary"
    warn "  (run ${C_WHT}podman login docker.io${C_RST} to get higher pull limits)"
  fi
}

# Resolve pull candidates for an image.
# docker.io/library/foo:tag  →  tries mirror first if not authed, hub as fallback
# Non-docker.io images       →  pulled directly, no mirror
_pull_candidates() {
  local image="$1"
  if [[ "${image}" == docker.io/* ]]; then
    local suffix="${image#docker.io/}"          # e.g. library/postgres:16-alpine
    local mirror_ref="mirror.gcr.io/${suffix}"
    if (( DOCKER_AUTHED )); then
      echo "${image}"          # authed: hub directly, no mirror needed
    else
      echo "${mirror_ref}"     # unauthenticated: mirror first
      echo "${image}"          # hub as last-resort (may hit rate limit)
    fi
  else
    echo "${image}"            # non-hub image: straight pull
  fi
}

# ─── image pull with mirror fallback + retry ──────────────────────────────────
# Usage: _pull_image <image-ref>
_pull_image() {
  local image="$1"

  # Already present locally? Skip entirely — no network, no rate-limit exposure.
  if podman image exists "${image}" 2>/dev/null; then
    dim "Image cached: ${image}"
    return 0
  fi

  # Build ordered list of refs to attempt
  local -a candidates
  mapfile -t candidates < <(_pull_candidates "${image}")

  local final_err=""
  for ref in "${candidates[@]}"; do
    local label="${ref}"
    [[ "${ref}" == mirror.gcr.io/* ]] && label="${ref} (mirror)"
    info "Pulling ${label} …"

    local pull_out pull_rc
    pull_out="$(podman pull "${ref}" 2>&1)"; pull_rc=$?

    if (( pull_rc == 0 )); then
      # If we pulled via mirror, tag it as the canonical name so containers
      # reference the expected image string without re-downloading.
      if [[ "${ref}" != "${image}" ]]; then
        podman tag "${ref}" "${image}" 2>/dev/null || true
        dim "Tagged mirror pull as ${image}"
      fi
      ok "Ready: ${image}"
      return 0
    fi

    # Auth/rate-limit hit even on mirror — surface clearly
    if echo "${pull_out}" | grep -qiE "unauthorized|invalid username|rate limit|toomanyrequests"; then
      warn "Rate-limited/auth error on ${ref}"
      final_err="rate-limit"
    else
      warn "Pull failed for ${ref}"
      dim "  ${pull_out}"
      final_err="network"
    fi
  done

  # All candidates exhausted
  echo ""
  err "Could not pull ${image} from any source."
  if [[ "${final_err}" == "rate-limit" ]]; then
    echo -e "\n  ${C_YLW}You've hit Docker Hub's anonymous pull limit.${C_RST}"
    echo -e "  ${C_BLD}Fix (pick one):${C_RST}"
    echo -e "  ${C_GRY}  A) Log in:${C_RST}  ${C_WHT}podman login docker.io${C_RST}  ${C_GRY}(free account, 100 pulls/6h)${C_RST}"
    echo -e "  ${C_GRY}  B) Wait ~6 hours for the anonymous limit to reset, then re-run.${C_RST}"
    echo -e "  ${C_GRY}  C) Add a permanent mirror to ~/.config/containers/registries.conf:${C_RST}"
    echo -e ""
    echo -e "  ${C_GRY}     unqualified-search-registries = [\"docker.io\"]${C_RST}"
    echo -e "  ${C_GRY}     [[registry]]${C_RST}"
    echo -e "  ${C_GRY}     prefix   = \"docker.io\"${C_RST}"
    echo -e "  ${C_GRY}     location = \"mirror.gcr.io\"${C_RST}"
    echo ""
    echo -e "  ${C_GRY}Already-running containers are untouched — just re-run devpods.sh.${C_RST}"
  fi
  echo ""
  die "Aborting."
}

# Pre-pull every image a pod needs BEFORE touching any containers.
# Clean failure here means no half-started pods.
_preflight_images() {
  local pod="$1"; shift
  local images=("$@")
  section "Preflight images for ${pod}"
  for img in "${images[@]}"; do
    _pull_image "${img}"
  done
  ok "All images ready for ${pod}."
}

# ─── pod launchers ────────────────────────────────────────────────────────────

_up_pg() {
  section "dev-pg-pod  (PostgreSQL 16 + pgweb)"
  local pod="dev-pg-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/postgres"

  _preflight_images "${pod}" \
    "docker.io/library/postgres:16-alpine" \
    "docker.io/sosedoff/pgweb:latest"

  _ensure_pod "${pod}" "5432:5432" "8081:8081"

  # PostgreSQL
  if ! podman container exists "${pod}-postgres" 2>/dev/null; then
    info "Starting PostgreSQL …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-postgres" \
      --health-cmd "pg_isready -U ${PG_USER}" \
      --health-interval 5s \
      --health-retries 10 \
      -e POSTGRES_USER="${PG_USER}" \
      -e POSTGRES_PASSWORD="${PG_PASS}" \
      -e POSTGRES_DB="${PG_DB}" \
      -v "${data}/postgres:/var/lib/postgresql/data:Z" \
      docker.io/library/postgres:16-alpine >/dev/null
    ok "PostgreSQL container started."
  else
    dim "PostgreSQL container already exists."
  fi

  _wait_healthy "${pod}-postgres"

  # pgweb
  if ! podman container exists "${pod}-pgweb" 2>/dev/null; then
    info "Starting pgweb …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-pgweb" \
      -e DATABASE_URL="postgres://${PG_USER}:${PG_PASS}@localhost:5432/${PG_DB}?sslmode=disable" \
      docker.io/sosedoff/pgweb:latest >/dev/null
    ok "pgweb started → http://localhost:8081"
  else
    dim "pgweb container already exists."
  fi
}

_up_mongo() {
  section "dev-mongo-pod  (MongoDB 7 RS + mongo-express)"
  local pod="dev-mongo-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/mongodb"

  _preflight_images "${pod}" \
    "docker.io/library/mongo:7" \
    "docker.io/library/mongo-express:latest"

  _ensure_pod "${pod}" "27017:27017" "8082:8081"

  # MongoDB
  if ! podman container exists "${pod}-mongodb" 2>/dev/null; then
    info "Starting MongoDB …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-mongodb" \
      --user 999:999 \
      --health-cmd "mongosh --quiet --eval \"db.adminCommand('ping').ok\" | grep -q 1" \
      --health-interval 5s \
      --health-retries 15 \
      -v "${data}/mongodb:/data/db:Z,U" \
      docker.io/library/mongo:7 \
      --replSet "${MONGO_RS}" --bind_ip_all >/dev/null
    ok "MongoDB container started."
  else
    dim "MongoDB container already exists."
  fi

  # Wait then initiate RS
  info "Waiting for MongoDB to be ready …"
  local attempts=0
  until podman exec "${pod}-mongodb" mongosh --quiet --eval "db.adminCommand('ping')" >/dev/null 2>&1; do
    sleep 2; (( attempts++ ))
    (( attempts > 30 )) && die "MongoDB did not become ready in time."
  done

  podman exec "${pod}-mongodb" mongosh --quiet --eval "
    try { rs.status(); print('RS already initialised'); }
    catch(e) {
      rs.initiate({ _id: '${MONGO_RS}', members: [{ _id: 0, host: 'localhost:27017' }] });
      print('RS initiated');
    }
  " >/dev/null 2>&1 && ok "Replica set: ${MONGO_RS}" || warn "RS init non-zero (may already be set)"

  # mongo-express
  if ! podman container exists "${pod}-mongoexpress" 2>/dev/null; then
    info "Starting mongo-express …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-mongoexpress" \
      -e ME_CONFIG_MONGODB_URL="mongodb://localhost:27017/?replicaSet=${MONGO_RS}" \
      -e ME_CONFIG_BASICAUTH_USERNAME="${ME_USER}" \
      -e ME_CONFIG_BASICAUTH_PASSWORD="${ME_PASS}" \
      -e ME_CONFIG_MONGODB_ENABLE_ADMIN=true \
      -e ME_CONFIG_OPTIONS_EDITORTHEME="dracula" \
      docker.io/library/mongo-express:latest >/dev/null
    ok "mongo-express started → http://localhost:8082  (${ME_USER}/${ME_PASS})"
  else
    dim "mongo-express container already exists."
  fi
}

_up_redis() {
  section "dev-redis-pod  (Redis 7 + RedisInsight)"
  local pod="dev-redis-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/redis" "${data}/redisinsight"
  # RedisInsight v2+ needs write access to /data/
  chmod 777 "${data}/redisinsight"

  _preflight_images "${pod}" \
    "docker.io/library/redis:7-alpine" \
    "docker.io/redis/redisinsight:latest"

  _ensure_pod "${pod}" "6379:6379" "8083:5540"

  # Redis
  if ! podman container exists "${pod}-redis" 2>/dev/null; then
    info "Starting Redis …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-redis" \
      --health-cmd "redis-cli -a ${REDIS_PASS} ping | grep -q PONG" \
      --health-interval 5s \
      -v "${data}/redis:/data:Z" \
      docker.io/library/redis:7-alpine \
      redis-server --requirepass "${REDIS_PASS}" --appendonly yes >/dev/null
    ok "Redis started."
  else
    dim "Redis container already exists."
  fi

  # RedisInsight
  if ! podman container exists "${pod}-redisinsight" 2>/dev/null; then
    info "Starting RedisInsight …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-redisinsight" \
      -v "${data}/redisinsight:/data:Z" \
      docker.io/redis/redisinsight:latest >/dev/null
    ok "RedisInsight started → http://localhost:8083"
  else
    dim "RedisInsight container already exists."
  fi
}

_up_mail() {
  section "dev-mail-pod  (Mailpit)"
  local pod="dev-mail-pod"

  _preflight_images "${pod}" "docker.io/axllent/mailpit:latest"

  _ensure_pod "${pod}" "1025:1025" "8025:8025"

  if ! podman container exists "${pod}-mailpit" 2>/dev/null; then
    info "Starting Mailpit …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-mailpit" \
      docker.io/axllent/mailpit:latest >/dev/null
    ok "Mailpit started → SMTP: localhost:1025  UI: http://localhost:8025"
  else
    dim "Mailpit container already exists."
  fi
}

_up_seq() {
  section "dev-seq-pod  (Seq)"
  local pod="dev-seq-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/seq"
  chmod 777 "${data}/seq"

  _preflight_images "${pod}" "docker.io/datalust/seq:latest"

  _ensure_pod "${pod}" "5341:80"

  if ! podman container exists "${pod}-seq" 2>/dev/null; then
    info "Starting Seq …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-seq" \
      -e ACCEPT_EULA=Y \
      -e SEQ_FIRSTRUN_NOAUTHENTICATION=true \
      -v "${data}/seq:/data:Z" \
      docker.io/datalust/seq:latest >/dev/null
    ok "Seq started → http://localhost:5341"
  else
    dim "Seq container already exists."
  fi
}

_up_rmq() {
  section "dev-rmq-pod  (RabbitMQ 3)"
  local pod="dev-rmq-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/rabbitmq"

  _preflight_images "${pod}" "docker.io/library/rabbitmq:3-management-alpine"

  _ensure_pod "${pod}" "5672:5672" "15672:15672"

  if ! podman container exists "${pod}-rabbitmq" 2>/dev/null; then
    info "Starting RabbitMQ …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-rabbitmq" \
      --health-cmd "rabbitmq-diagnostics -q ping" \
      --health-interval 10s \
      --health-retries 10 \
      -e RABBITMQ_DEFAULT_USER="${RMQ_USER}" \
      -e RABBITMQ_DEFAULT_PASS="${RMQ_PASS}" \
      -v "${data}/rabbitmq:/var/lib/rabbitmq:Z" \
      docker.io/library/rabbitmq:3-management-alpine >/dev/null
    ok "RabbitMQ started → AMQP: localhost:5672  UI: http://localhost:15672  (${RMQ_USER}/${RMQ_PASS})"
  else
    dim "RabbitMQ container already exists."
  fi
}

_up_nats() {
  section "dev-nats-pod  (NATS 2 + JetStream)"
  local pod="dev-nats-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/nats"

  _preflight_images "${pod}" "docker.io/library/nats:2-alpine"

  _ensure_pod "${pod}" "4222:4222" "8222:8222" "6222:6222"

  # Write NATS config inline
  local nats_conf="${data}/nats/server.conf"
  cat > "${nats_conf}" <<'NATSCONF'
port:      4222
http_port: 8222

jetstream {
  store_dir:        /data
  max_memory_store: 512mb
  max_file_store:   4gb
}

debug: false
logtime: true
NATSCONF

  if ! podman container exists "${pod}-nats" 2>/dev/null; then
    info "Starting NATS …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-nats" \
      -v "${data}/nats:/data:Z" \
      docker.io/library/nats:2-alpine \
      -c /data/server.conf >/dev/null
    ok "NATS started → nats://localhost:4222  Monitor: http://localhost:8222"
  else
    dim "NATS container already exists."
  fi
}

_up_sms() {
  section "dev-sms-pod  (devsms)"
  local pod="dev-sms-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/devsms"

  _preflight_images "${pod}" "ghcr.io/mrmeaow/devsms:latest"

  _ensure_pod "${pod}" "4000:4000" "5153:5153"

  if ! podman container exists "${pod}-devsms" 2>/dev/null; then
    info "Starting devsms …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-devsms" \
      -v "${data}/devsms:/app/data:Z" \
      ghcr.io/mrmeaow/devsms:latest >/dev/null
    ok "devsms started → API: http://localhost:4000  UI: http://localhost:5153"
  else
    dim "devsms container already exists."
  fi
}

_up_minio() {
  section "dev-minio-pod  (MinIO)"
  local pod="dev-minio-pod"
  local data="${DATA_ROOT}/${pod}"
  mkdir -p "${data}/minio"

  _preflight_images "${pod}" "docker.io/minio/minio:latest"

  _ensure_pod "${pod}" "9000:9000" "9001:9001"

  if ! podman container exists "${pod}-minio" 2>/dev/null; then
    info "Starting MinIO …"
    podman run -d \
      --pod "${pod}" \
      --name "${pod}-minio" \
      -e MINIO_ROOT_USER="${MINIO_ROOT_USER}" \
      -e MINIO_ROOT_PASSWORD="${MINIO_ROOT_PASS}" \
      -v "${data}/minio:/data:Z" \
      docker.io/minio/minio:latest \
      server /data --console-address ":9001" >/dev/null
    ok "MinIO started → API: http://localhost:9000  Console: http://localhost:9001"
  else
    dim "MinIO container already exists."
  fi
}

# ─── pod name resolver ────────────────────────────────────────────────────────
_resolve_pods() {
  local requested=("$@")
  local resolved=()
  local seen=" "

  (( ${#requested[@]} == 0 )) && die "No pod target provided. Example: devpods up pg"

  for input in "${requested[@]}"; do
    if [[ "${input}" == "all" ]]; then
      for pod in "${ALL_PODS[@]}"; do
        [[ "${seen}" == *" ${pod} "* ]] || {
          resolved+=("${pod}")
          seen+="${pod} "
        }
      done
      continue
    fi

    local pod_name="${ALIAS_MAP[${input}]:-}"
    [[ -z "${pod_name}" ]] && die "Unknown pod alias '${input}'. Valid: ${!ALIAS_MAP[*]} all"
    [[ "${seen}" == *" ${pod_name} "* ]] || {
      resolved+=("${pod_name}")
      seen+="${pod_name} "
    }
  done

  echo "${resolved[@]}"
}

_launch_pod() {
  local pod="$1"
  case "${pod}" in
    dev-pg-pod)    _up_pg    ;;
    dev-mongo-pod) _up_mongo ;;
    dev-redis-pod) _up_redis ;;
    dev-mail-pod)  _up_mail  ;;
    dev-seq-pod)   _up_seq   ;;
    dev-rmq-pod)   _up_rmq   ;;
    dev-nats-pod)  _up_nats  ;;
    dev-sms-pod)   _up_sms   ;;
    dev-minio-pod) _up_minio ;;
    *) die "No launcher for pod '${pod}'" ;;
  esac
}

# ─── status table ─────────────────────────────────────────────────────────────
_status() {
  section "devpods status"
  printf "\n  ${C_BLD}%-20s %-12s %s${C_RST}\n" "POD" "STATE" "ENDPOINTS"
  printf "  %s\n" "──────────────────────────────────────────────────────────────────"

  declare -A ENDPOINTS=(
    [dev-pg-pod]="postgres://localhost:5432  pgweb→http://localhost:8081"
    [dev-mongo-pod]="mongodb://localhost:27017/?replicaSet=${MONGO_RS}  mongo-express→http://localhost:8082"
    [dev-redis-pod]="redis://localhost:6379  RedisInsight→http://localhost:8083"
    [dev-mail-pod]="SMTP→localhost:1025  UI→http://localhost:8025"
    [dev-seq-pod]="http://localhost:5341"
    [dev-rmq-pod]="amqp://localhost:5672  UI→http://localhost:15672"
    [dev-nats-pod]="nats://localhost:4222  monitor→http://localhost:8222"
    [dev-sms-pod]="devsms API→:4000  UI→:5153"
    [dev-minio-pod]="MinIO API→:9000  Console→:9001"
  )

  for pod in "${ALL_PODS[@]}"; do
    local state="stopped"
    local colour="${C_RED}"
    if _pod_exists "${pod}"; then
      if _pod_running "${pod}"; then
        state="running"; colour="${C_GRN}"
      else
        state="degraded"; colour="${C_YLW}"
      fi
    fi
    printf "  ${C_BLD}%-20s${C_RST} ${colour}%-12s${C_RST} ${C_GRY}%s${C_RST}\n" \
      "${pod}" "${state}" "${ENDPOINTS[${pod}]}"
  done
  echo ""
}

# ─── usage ────────────────────────────────────────────────────────────────────
_usage() {
  cat <<EOF

${C_BLD}${C_CYN}🦭 DevPods${C_RST} v${DEVPODS_VERSION} — Instant Local Infrastructure via Podman

${C_BLD}Usage:${C_RST}
  devpods <command> [pod ... | all]

${C_BLD}Commands:${C_RST}
  up     [pod ...|all] Start pod(s)             (explicit target required)
  down   [pod ...|all] Stop and remove pod(s)
  reset  [pod ...|all] Stop + wipe data for pod(s)
  status              Show state of all pods
  help                This message

${C_BLD}Pod aliases:${C_RST}
  pg       → dev-pg-pod      (PostgreSQL + pgweb)
  mongo    → dev-mongo-pod   (MongoDB RS + mongo-express)
  redis    → dev-redis-pod   (Redis + RedisInsight)
  mail     → dev-mail-pod    (Mailpit)
  seq      → dev-seq-pod     (Seq)
  rmq      → dev-rmq-pod     (RabbitMQ)
  nats     → dev-nats-pod    (NATS + JetStream)
  sms      → dev-sms-pod     (devsms)
  minio    → dev-minio-pod   (MinIO)

${C_BLD}One-liner (curl | bash):${C_RST}
  curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- up pg
  curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- down all
  curl -fsSL https://gist.githubusercontent.com/<you>/devpods.sh/raw | bash -s -- status

${C_BLD}Data root:${C_RST} ~/.devpods/
${C_BLD}Credentials:${C_RST} ~/.devpods/.env  (auto-created with defaults on first run)

EOF
}

# ─── summary card + cheatsheet file ──────────────────────────────────────────
_summary() {
  local cheatsheet="${DATA_ROOT}/cheatsheet.txt"

  # ── plain-text version (written to file, no ANSI) ─────────────────────────
  cat > "${cheatsheet}" <<CHEAT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  devpods — Connection Cheatsheet
  Generated: $(date '+%Y-%m-%d %H:%M:%S %Z')
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  SERVICE          CONNECTION
  ─────────────────────────────────────────────────────────────
  PostgreSQL       postgresql://${PG_USER}:${PG_PASS}@localhost:5432/${PG_DB}
  pgweb            http://localhost:8081

  MongoDB          mongodb://localhost:27017/?replicaSet=${MONGO_RS}
  mongo-express    http://localhost:8082  (${ME_USER} / ${ME_PASS})

  Redis            redis://:${REDIS_PASS}@localhost:6379
  RedisInsight     http://localhost:8083

  Mailpit SMTP     localhost:1025
  Mailpit UI       http://localhost:8025

  Seq              http://localhost:5341

  RabbitMQ         amqp://${RMQ_USER}:${RMQ_PASS}@localhost:5672
  RMQ Management   http://localhost:15672  (${RMQ_USER} / ${RMQ_PASS})

  NATS             nats://localhost:4222
  NATS Monitor     http://localhost:8222

  devsms API       http://localhost:4000
  devsms UI        http://localhost:5153

  MinIO API        http://localhost:9000
  MinIO Console    http://localhost:9001  (${MINIO_ROOT_USER} / ${MINIO_ROOT_PASS})

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Credentials:  ~/.devpods/.env
  Tear down:    bash devpods.sh down all
  Status:       bash devpods.sh status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHEAT

  # ── coloured terminal version ─────────────────────────────────────────────
  echo -e "\n${C_BLD}${C_CYN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RST}"
  echo -e "${C_BLD}  devpods — Connection Cheatsheet${C_RST}"
  echo -e "${C_BLD}${C_CYN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RST}"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "PostgreSQL"     "postgresql://${PG_USER}:${PG_PASS}@localhost:5432/${PG_DB}"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "pgweb"         "http://localhost:8081"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "MongoDB"        "mongodb://localhost:27017/?replicaSet=${MONGO_RS}"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "mongo-express" "http://localhost:8082  (${ME_USER} / ${ME_PASS})"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "Redis"          "redis://:${REDIS_PASS}@localhost:6379"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "RedisInsight"  "http://localhost:8083"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "Mailpit SMTP"   "localhost:1025"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "Mailpit UI"    "http://localhost:8025"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "Seq"            "http://localhost:5341"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "RabbitMQ"       "amqp://${RMQ_USER}:${RMQ_PASS}@localhost:5672"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "RMQ Mgmt"      "http://localhost:15672  (${RMQ_USER} / ${RMQ_PASS})"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "NATS"           "nats://localhost:4222"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "NATS Monitor"  "http://localhost:8222"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "devsms API"     "http://localhost:4000"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "devsms UI"      "http://localhost:5153"
  printf "  ${C_BLD}%-16s${C_RST} %s\n"   "MinIO API"      "http://localhost:9000"
  printf "  ${C_GRY}%-16s${C_RST} ${C_GRY}%s${C_RST}\n" "MinIO Console" "http://localhost:9001  (${MINIO_ROOT_USER} / ${MINIO_ROOT_PASS})"
  echo -e "${C_BLD}${C_CYN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C_RST}"
  echo -e "  ${C_GRY}Saved: ${C_WHT}${cheatsheet}${C_RST}"
  echo -e "  ${C_GRY}Tear down: bash devpods.sh down all${C_RST}"
  echo ""
}

# ─── entrypoint ───────────────────────────────────────────────────────────────
main() {
  banner "🦭 DevPods v${DEVPODS_VERSION}"

  local cmd="${1:-help}"

  case "${cmd}" in
    help|--help|-h)
      _usage
      return 0
      ;;
  esac

  _check_system
  _load_env

  case "${cmd}" in
    up)
      local pods
      IFS=' ' read -ra pods <<< "$(_resolve_pods "${@:2}")"
      for p in "${pods[@]}"; do _launch_pod "${p}"; done
      _summary
      ;;
    down)
      section "Stopping pods"
      local pods
      IFS=' ' read -ra pods <<< "$(_resolve_pods "${@:2}")"
      for p in "${pods[@]}"; do _stop_pod "${p}"; done
      ok "Done."
      ;;
    reset)
      section "Resetting pods (stop + wipe data)"
      warn "This will DELETE all data for the selected pod(s). Ctrl-C to abort …"
      sleep 3
      local pods
      IFS=' ' read -ra pods <<< "$(_resolve_pods "${@:2}")"
      for p in "${pods[@]}"; do _reset_pod "${p}"; done
      ok "Reset complete. Re-run 'up' to recreate."
      ;;
    status)
      _status
      ;;
    *)
      err "Unknown command: ${cmd}"
      _usage
      exit 1
      ;;
  esac
}

main "$@"