run

#!/usr/bin/env bash
#
# OrcPub / Dungeon Master's Vault — Docker Setup Script
#
# Prepares everything needed to run the application via Docker Compose:
#   1. Generates secure random passwords and a signing secret
#   2. Creates a .env file (or uses an existing one)
#   3. Generates self-signed SSL certificates (if missing)
#   4. Creates required directories (data, logs, deploy/homebrew)
#
# Usage:
#   ./${SCRIPT_NAME}            # Interactive mode — prompts for optional values
#   ./${SCRIPT_NAME} --auto     # Non-interactive — accepts all defaults
#   ./${SCRIPT_NAME} --help     # Show usage
#

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"
ENV_FILE="${SCRIPT_DIR}/.env"

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

color_green=$'\033[0;32m'
color_yellow=$'\033[1;33m'
color_red=$'\033[0;31m'
color_cyan=$'\033[0;36m'
color_magenta=$'\033[0;35m'
color_reset=$'\033[0m'

info()    { printf '%s[INFO]%s  %s\n' "$color_green" "$color_reset" "$*"; }
warn()    { printf '%s[WARN]%s  %s\n' "$color_yellow" "$color_reset" "$*"; }
change()  { printf '%s[FIXD]%s  %s\n' "$color_magenta" "$color_reset" "$*"; }
error()   { printf '%s[ERROR]%s %s\n' "$color_red" "$color_reset" "$*" >&2; }
success() { printf '\n%s=== %s ===%s\n' "$color_green" "$*" "$color_reset"; }
header()  { printf '\n%s=== %s ===%s\n\n' "$color_cyan" "$*" "$color_reset"; }
next()    { printf '%s  ▸%s %s\n' "$color_cyan" "$color_reset" "$*"; }

# Read a variable value from a .env file, stripping Windows \r line endings.
# Usage: val=$(read_env_val "VAR_NAME" "/path/to/.env")
read_env_val() {
  grep -m1 "^${1}=" "$2" 2>/dev/null | cut -d= -f2- | tr -d '\r' || true
}

# Source a .env file safely (strips Windows \r line endings).
# Usage: source_env "/path/to/.env"
source_env() {
  # shellcheck disable=SC1090
  . <(tr -d '\r' < "$1")
}

# Set a variable in a .env file. Uses awk to avoid sed delimiter issues with URLs.
# Usage: set_env_val "VAR_NAME" "value" "/path/to/.env"
set_env_val() {
  local var="$1" val="$2" file="$3"
  if grep -q "^${var}=" "$file" 2>/dev/null; then
    awk -v var="$var" -v val="$val" '{
      if (index($0, var"=") == 1) print var"="val; else print
    }' "$file" > "${file}.tmp"
    mv "${file}.tmp" "$file"
  else
    echo "${var}=${val}" >> "$file"
  fi
}

generate_password() {
  # Generate a URL-safe random password (no special chars that break URLs/YAML)
  local length="${1:-24}"
  if command -v openssl &>/dev/null; then
    openssl rand -base64 "$((length * 2))" | tr -d '/+=' | head -c "$length"
  elif [ -r /dev/urandom ]; then
    tr -dc 'A-Za-z0-9' < /dev/urandom | head -c "$length"
  else
    error "Cannot generate random password: no openssl or /dev/urandom available"
    exit 1
  fi
}

# Generate docker-compose.secrets.yaml and wire COMPOSE_FILE into .env.
# Usage: write_compose_secrets "file"   → file-based secrets
#        write_compose_secrets "external" → Swarm external secrets
write_compose_secrets() {
  local mode="$1"  # "file" or "external"
  local secrets_compose="${SCRIPT_DIR}/docker-compose.secrets.yaml"
  local compose_file_var="docker-compose.yaml:docker-compose.secrets.yaml"

  if [ -f "$secrets_compose" ] && [ "$FORCE_MODE" = "false" ]; then
    warn "docker-compose.secrets.yaml already exists. Use --force to overwrite."
    return 0
  fi

  if [ "$mode" = "file" ]; then
    cat > "$secrets_compose" <<YAML
# Generated by ./${SCRIPT_NAME} --secrets
# Compose merges this with docker-compose.yaml automatically via COMPOSE_FILE.
secrets:
  datomic_password:
    file: ./secrets/datomic_password
  admin_password:
    file: ./secrets/admin_password
  signature:
    file: ./secrets/signature

services:
  orcpub:
    secrets:
      - datomic_password
      - signature
  datomic:
    secrets:
      - datomic_password
      - admin_password
YAML
  else
    cat > "$secrets_compose" <<YAML
# Generated by ./${SCRIPT_NAME} --swarm
# Compose merges this with docker-compose.yaml automatically via COMPOSE_FILE.
secrets:
  datomic_password:
    external: true
  admin_password:
    external: true
  signature:
    external: true

services:
  orcpub:
    secrets:
      - datomic_password
      - signature
  datomic:
    secrets:
      - datomic_password
      - admin_password
YAML
  fi

  change "Created docker-compose.secrets.yaml"

  # Add COMPOSE_FILE to .env so compose merges both files automatically
  if [ -f "$ENV_FILE" ]; then
    local current_cf
    current_cf=$(read_env_val COMPOSE_FILE "$ENV_FILE")
    if [ -z "$current_cf" ]; then
      {
        echo ""
        echo "# --- Compose file merge (secrets) ---"
        echo "COMPOSE_FILE=${compose_file_var}"
      } >> "$ENV_FILE"
      change "Added COMPOSE_FILE to .env (compose will merge both files)"
    elif [ "$current_cf" != "$compose_file_var" ]; then
      warn "COMPOSE_FILE already set in .env: ${current_cf}"
      warn "Make sure it includes docker-compose.secrets.yaml"
    fi
  else
    warn "No .env file — add to your environment:"
    warn "  export COMPOSE_FILE=${compose_file_var}"
  fi
}

# Switch transactor host binding between Compose and Swarm modes.
# Usage: switch_transactor_host "compose"  → host=datomic (Compose DNS bind)
#        switch_transactor_host "swarm"    → host=0.0.0.0 (Swarm all-interfaces)
switch_transactor_host() {
  local mode="$1"
  local template="${SCRIPT_DIR}/docker/transactor.properties.template"
  [ -f "$template" ] || return 0

  if [ "$mode" = "compose" ]; then
    if grep -q '^host=0\.0\.0\.0' "$template"; then
      sed -i 's/^host=0\.0\.0\.0$/#host=0.0.0.0/' "$template"
      sed -i 's/^#host=datomic$/host=datomic/' "$template"
      change "Transactor host: 0.0.0.0 → datomic (Compose bind)"
    fi
  elif [ "$mode" = "swarm" ]; then
    if grep -q '^host=datomic' "$template"; then
      sed -i 's/^host=datomic$/#host=datomic/' "$template"
      sed -i 's/^#host=0\.0\.0\.0$/host=0.0.0.0/' "$template"
      change "Transactor host: datomic → 0.0.0.0 (Swarm bind)"
    fi
  fi
}

# Read DATOMIC_PASSWORD, ADMIN_PASSWORD, SIGNATURE from .env + shell env.
# Sets _pw_datomic, _pw_admin, _pw_signature. Exits on missing values.
# Usage: read_passwords "--secrets" (label for error message)
read_passwords() {
  local mode_label="$1"
  _pw_datomic=""
  _pw_admin=""
  _pw_signature=""

  if [ -f "$ENV_FILE" ]; then
    info "Reading passwords from .env"
    _pw_datomic=$(read_env_val DATOMIC_PASSWORD "$ENV_FILE")
    _pw_admin=$(read_env_val ADMIN_PASSWORD "$ENV_FILE")
    _pw_signature=$(read_env_val SIGNATURE "$ENV_FILE")
  fi

  # Fill gaps from shell env vars (for admins who export directly)
  _pw_datomic="${_pw_datomic:-${DATOMIC_PASSWORD:-}}"
  _pw_admin="${_pw_admin:-${ADMIN_PASSWORD:-}}"
  _pw_signature="${_pw_signature:-${SIGNATURE:-}}"

  if [ -z "$_pw_datomic" ] || [ -z "$_pw_admin" ] || [ -z "$_pw_signature" ]; then
    error "Could not find all required passwords."
    error "Checked .env file and shell environment variables."
    [ -z "$_pw_datomic" ]   && error "  DATOMIC_PASSWORD — not found"
    [ -z "$_pw_admin" ]     && error "  ADMIN_PASSWORD — not found"
    [ -z "$_pw_signature" ] && error "  SIGNATURE — not found"
    echo ""
    error "Either create a .env file (./${SCRIPT_NAME}) or export the"
    error "variables in your shell before running ${mode_label}."
    exit 1
  fi
}

# Check that a file exists, incrementing ERRORS if not.
# Usage: check_file "label" "/path/to/file"
check_file() {
  local label="$1" path="$2"
  if [ -f "$path" ]; then
    info "  ${label}: OK"
  else
    warn "  ${label}: MISSING"
    WARNING_MSGS+=("${label} is missing")
    ERRORS=$((ERRORS + 1))
  fi
}

# Check that a directory exists, incrementing ERRORS if not.
# Usage: check_dir "label" "/path/to/dir"
check_dir() {
  local label="$1" path="$2"
  if [ -d "$path" ]; then
    info "  ${label}: OK"
  else
    warn "  ${label}: MISSING"
    WARNING_MSGS+=("${label} is missing")
    ERRORS=$((ERRORS + 1))
  fi
}

# Check if a shell env var conflicts with .env value, incrementing ERRORS if so.
# Usage: check_env_conflict "VAR_NAME"
check_env_conflict() {
  local var_name="$1"
  local env_val="${!var_name:-}"
  local file_val
  file_val=$(read_env_val "$var_name" "$ENV_FILE")

  if [ -n "$env_val" ] && [ -n "$file_val" ] && [ "$env_val" != "$file_val" ]; then
    warn "  Shell \$${var_name} differs from .env value"
    warn "    Shell: ${env_val}"
    warn "    .env:  ${file_val}"
    ENV_CONFLICTS+=("$var_name")
    WARNING_MSGS+=("\$${var_name}: shell value overrides .env")
    ERRORS=$((ERRORS + 1))
  fi
}

# Build a docker compose command, prefixing with env -u for each shell/env conflict.
# Usage: build_compose_cmd "docker compose up --build -d"
build_compose_cmd() {
  local base_cmd="$1"
  if [ "${#ENV_CONFLICTS[@]}" -gt 0 ]; then
    local prefix=""
    for var in "${ENV_CONFLICTS[@]}"; do
      prefix="${prefix}env -u ${var} "
    done
    echo "${prefix}${base_cmd}"
  else
    echo "$base_cmd"
  fi
}

prompt_value() {
  local prompt_text="$1"
  local default_value="$2"
  local result

  if [ "${AUTO_MODE:-false}" = "true" ]; then
    echo "$default_value"
    return
  fi

  if [ -n "$default_value" ]; then
    read -rp "${prompt_text} [${default_value}]: " result || true
    echo "${result:-$default_value}"
  else
    read -rp "${prompt_text}: " result || true
    echo "$result"
  fi
}

# Confirm an action, auto-accepting in auto mode.
# Returns 0 (yes) or 1 (no). Usage:
#   if confirm_action "Stop Compose services now?"; then ...
confirm_action() {
  local prompt_text="$1"
  if [ "${AUTO_MODE:-false}" = "true" ]; then
    return 0
  fi
  local _answer
  read -rp "${prompt_text} [Y/n]: " _answer || true
  [[ "${_answer,,}" =~ ^(y|)$ ]]
}

# Write .env file using current variable values.
# Expects PORT, ADMIN_PASSWORD, DATOMIC_PASSWORD, SIGNATURE, EMAIL_*, ORCPUB_IMAGE,
# DATOMIC_IMAGE, INIT_ADMIN_* to be set in scope before calling.
write_env_file() {
  cat > "$ENV_FILE" <<EOF
# ============================================================================
# Dungeon Master's Vault — Docker Environment Configuration
# Generated by run on $(date -u +"%Y-%m-%d %H:%M:%S UTC")
# ============================================================================

# --- Application ---
PORT=${PORT}

# --- Docker Images ---
# Set these to version your builds (e.g. orcpub-app:v2.6.0)
# Leave empty to use default names (orcpub-app, orcpub-datomic)
ORCPUB_IMAGE=${ORCPUB_IMAGE}
DATOMIC_IMAGE=${DATOMIC_IMAGE}

# --- Datomic Database ---
# ADMIN_PASSWORD — internal storage admin. Controls who can create/delete
#   databases on the transactor. Only the transactor uses it; the app never sees it.
# DATOMIC_PASSWORD — peer connection password. The transactor and app must share
#   the same value. The app appends it to DATOMIC_URL at startup automatically.
#
# WARNING: Both passwords are locked into the database on first startup.
#   Changing them later will prevent the transactor from starting (ADMIN_PASSWORD)
#   or the app from connecting (DATOMIC_PASSWORD). Your data is NOT lost — set
#   the password back, or use the _OLD vars below for graceful rotation.
ADMIN_PASSWORD=${ADMIN_PASSWORD}
DATOMIC_PASSWORD=${DATOMIC_PASSWORD}
DATOMIC_URL=datomic:dev://datomic:4334/orcpub

# --- Transactor Tuning ---
# These rarely need changing. See docker/transactor.properties.template.
ALT_HOST=127.0.0.1
ENCRYPT_CHANNEL=true
# Password rotation: set the OLD var to the previous password, then change the
# main var above. The transactor accepts both during the transition. Remove the
# OLD var after restarting and confirming everything works.
# ADMIN_PASSWORD_OLD=
# DATOMIC_PASSWORD_OLD=

# --- Security ---
# Secret used to sign JWT tokens (20+ characters recommended)
SIGNATURE=${SIGNATURE}

# --- Email (SMTP) ---
EMAIL_SERVER_URL=${EMAIL_SERVER_URL}
EMAIL_ACCESS_KEY=${EMAIL_ACCESS_KEY}
EMAIL_SECRET_KEY=${EMAIL_SECRET_KEY}
EMAIL_SERVER_PORT=${EMAIL_SERVER_PORT}
EMAIL_FROM_ADDRESS=${EMAIL_FROM_ADDRESS}
EMAIL_ERRORS_TO=${EMAIL_ERRORS_TO}
EMAIL_SSL=${EMAIL_SSL}
EMAIL_TLS=${EMAIL_TLS}

# --- SSL (Nginx) ---
# Set to 'true' after running snakeoil.sh or providing your own certs
# SSL_CERT_PATH=./deploy/snakeoil.crt
# SSL_KEY_PATH=./deploy/snakeoil.key

# --- Initial Admin User (optional) ---
# Set these to create an admin account on first run:
#   ./docker-user.sh init
# Safe to run multiple times — duplicates are skipped.
INIT_ADMIN_USER=${INIT_ADMIN_USER}
INIT_ADMIN_EMAIL=${INIT_ADMIN_EMAIL}
INIT_ADMIN_PASSWORD=${INIT_ADMIN_PASSWORD}
EOF
  chmod 600 "$ENV_FILE"
  change ".env file created at ${ENV_FILE} (permissions: 600)"
}

# Create required directories if they don't exist.
setup_directories() {
  for dir in "${SCRIPT_DIR}/data" "${SCRIPT_DIR}/logs" "${SCRIPT_DIR}/backups" "${SCRIPT_DIR}/deploy/homebrew"; do
    if [ ! -d "$dir" ]; then
      mkdir -p "$dir"
      change "Created directory: ${dir#"${SCRIPT_DIR}"/}"
    else
      info "Directory exists:  ${dir#"${SCRIPT_DIR}"/}"
    fi
  done
}

# Generate self-signed SSL certificate if none exists.
setup_ssl_certs() {
  local cert="${SCRIPT_DIR}/deploy/snakeoil.crt"
  local key="${SCRIPT_DIR}/deploy/snakeoil.key"
  if [ -f "$cert" ] && [ -f "$key" ]; then
    info "SSL certificates already exist. Skipping generation."
  elif command -v openssl &>/dev/null; then
    info "Generating self-signed SSL certificate..."
    openssl req \
      -subj "/C=US/ST=State/L=City/O=OrcPub/OU=Dev/CN=localhost" \
      -x509 -nodes -days 365 -newkey rsa:2048 \
      -keyout "$key" -out "$cert" 2>/dev/null
    change "SSL certificate generated (valid for 365 days)."
  else
    warn "openssl not found — cannot generate SSL certificates."
    warn "Install openssl and run: ./deploy/snakeoil.sh"
  fi
}

# Generate a fresh .env through prompts (interactive) or defaults (--auto).
# Also creates directories and SSL certs. Works in both modes because
# prompt_value() returns the default silently when AUTO_MODE=true.
generate_env() {
  header "Database Passwords"

  DEFAULT_ADMIN_PW="$(generate_password 24)"
  DEFAULT_DATOMIC_PW="$(generate_password 24)"
  DEFAULT_SIGNATURE="$(generate_password 32)"

  echo ""
  echo "  Datomic uses two passwords (both locked into the DB on first startup):"
  echo "    Admin password  — internal, controls database create/delete"
  echo "    Peer password   — shared between transactor and app for connections"

  if [ -f "${SCRIPT_DIR}/data/db/datomic.mv.db" ]; then
    echo ""
    warn "Existing database found in data/db/."
    warn "The admin password is locked into this database. If you set a new"
    warn "password, the transactor will fail to start. Either:"
    warn "  1. Keep the same admin password as before"
    warn "  2. Wipe the database first: rm -rf data/db/*"
  fi

  echo ""
  ADMIN_PASSWORD=$(prompt_value "Admin password" "$DEFAULT_ADMIN_PW")
  DATOMIC_PASSWORD=$(prompt_value "Peer password" "$DEFAULT_DATOMIC_PW")
  SIGNATURE=$(prompt_value "JWT signing secret (20+ chars)" "$DEFAULT_SIGNATURE")

  header "Application"

  PORT=$(prompt_value "Application port" "8890")

  _image_tag=$(prompt_value "Image tag (leave empty for default)" "")
  if [ -n "$_image_tag" ]; then
    ORCPUB_IMAGE="orcpub-app:${_image_tag}"
    DATOMIC_IMAGE="orcpub-datomic:${_image_tag}"
  else
    ORCPUB_IMAGE=""
    DATOMIC_IMAGE=""
  fi
  EMAIL_SERVER_URL=$(prompt_value "SMTP server URL (leave empty to skip email)" "")
  EMAIL_ACCESS_KEY=""
  EMAIL_SECRET_KEY=""
  EMAIL_SERVER_PORT="587"
  EMAIL_FROM_ADDRESS=""
  EMAIL_ERRORS_TO=""
  EMAIL_SSL="FALSE"
  EMAIL_TLS="FALSE"

  if [ -n "$EMAIL_SERVER_URL" ]; then
    EMAIL_ACCESS_KEY=$(prompt_value "SMTP username" "")
    EMAIL_SECRET_KEY=$(prompt_value "SMTP password" "")
    EMAIL_SERVER_PORT=$(prompt_value "SMTP port" "587")
    EMAIL_FROM_ADDRESS=$(prompt_value "From email address" "no-reply@orcpub.com")
    EMAIL_ERRORS_TO=$(prompt_value "Error notification email" "")
    EMAIL_SSL=$(prompt_value "Use SSL? (TRUE/FALSE)" "FALSE")
    EMAIL_TLS=$(prompt_value "Use TLS? (TRUE/FALSE)" "FALSE")
  fi

  header "Initial Admin User"

  INIT_ADMIN_USER="${INIT_ADMIN_USER:-}"
  INIT_ADMIN_EMAIL="${INIT_ADMIN_EMAIL:-}"
  INIT_ADMIN_PASSWORD="${INIT_ADMIN_PASSWORD:-}"

  if [ -n "$INIT_ADMIN_USER" ] && [ -n "$INIT_ADMIN_EMAIL" ] && [ -n "$INIT_ADMIN_PASSWORD" ]; then
    info "Using admin user from environment: ${INIT_ADMIN_USER} <${INIT_ADMIN_EMAIL}>"
  elif [ "${AUTO_MODE}" = "true" ]; then
    INIT_ADMIN_USER="admin"
    INIT_ADMIN_EMAIL="admin@localhost"
    INIT_ADMIN_PASSWORD=$(generate_password 16)
    change "Generated admin user: ${INIT_ADMIN_USER} <${INIT_ADMIN_EMAIL}>"
    change "Generated admin password: ${INIT_ADMIN_PASSWORD}"
    info "Change these in .env before going to production."
  else
    info "Optionally create an initial admin account."
    info "You can skip this and create users later with ./docker-user.sh"
    echo ""
    INIT_ADMIN_USER=$(prompt_value "Admin username (leave empty to skip)" "")
    if [ -n "$INIT_ADMIN_USER" ]; then
      _default_email="${INIT_ADMIN_USER}@example.com"
      _default_pw="$(generate_password 16)"
      INIT_ADMIN_EMAIL=$(prompt_value "Admin email" "$_default_email")
      INIT_ADMIN_PASSWORD=$(prompt_value "Admin password" "$_default_pw")
      if [ -z "$INIT_ADMIN_EMAIL" ] || [ -z "$INIT_ADMIN_PASSWORD" ]; then
        warn "Email and password are required. Skipping admin user setup."
        INIT_ADMIN_USER=""
        INIT_ADMIN_EMAIL=""
        INIT_ADMIN_PASSWORD=""
      fi
    fi
  fi

  info "Writing .env file..."
  write_env_file
  setup_directories
  setup_ssl_certs
  echo ""
}

usage() {
  cat <<USAGE
Usage: ./${SCRIPT_NAME} [OPTIONS]

No flags (default):
  ./${SCRIPT_NAME}                    Full pipeline: setup -> build -> up (interactive)
  ./${SCRIPT_NAME} --auto             Same, non-interactive (CI/scripting)

Individual steps:
  --check             Validate .env and environment (read-only)
  --build             Build Docker images only
  --up                Deploy as a Docker Swarm stack
  --down              Teardown (auto-detects Swarm vs Compose)

Setup & secrets:
  --secrets           Convert .env passwords to Docker secret files
  --swarm             Convert .env passwords to Docker Swarm secrets
  --upgrade           Update an existing .env to the latest format
  --upgrade-secrets   Upgrade .env + create Docker secret files (one step)
  --upgrade-swarm     Upgrade .env + create Swarm secrets (one step)

Modifiers:
  --auto              Non-interactive mode; accept all defaults
  --force             Overwrite existing .env file
  --help              Show this help message

Swarm (flags compose together):
  ./${SCRIPT_NAME} --swarm --auto --build --up   # Zero to running stack

Examples:
  ./${SCRIPT_NAME}                    # Full pipeline — interactive
  ./${SCRIPT_NAME} --auto             # Full pipeline — accept defaults (CI)
  ./${SCRIPT_NAME} --down             # Stop everything
  ./${SCRIPT_NAME} --check            # Validate without changes
  ./${SCRIPT_NAME} --build            # Build images only
  ./${SCRIPT_NAME} --upgrade          # Fix old .env format
  ./${SCRIPT_NAME} --swarm --auto     # Generate .env + init Swarm + create secrets
  ./${SCRIPT_NAME} --build --up       # Build + deploy (Swarm only)
USAGE
}

# ---------------------------------------------------------------------------
# Parse arguments
# ---------------------------------------------------------------------------

AUTO_MODE=false
BUILD_MODE=false
CHECK_MODE=false
DOWN_MODE=false
UP_MODE=false
FORCE_MODE=false
SECRETS_MODE=false
SWARM_MODE=false
UPGRADE_MODE=false

for arg in "$@"; do
  case "$arg" in
    --auto)    AUTO_MODE=true ;;
    --check)   CHECK_MODE=true ;;
    --build)   BUILD_MODE=true ;;
    --down)    DOWN_MODE=true ;;
    --up)      UP_MODE=true ;;
    --force)   FORCE_MODE=true ;;
    --secrets)         SECRETS_MODE=true ;;
    --swarm)           SWARM_MODE=true ;;
    --upgrade)         UPGRADE_MODE=true ;;
    --upgrade-swarm)   UPGRADE_MODE=true; SWARM_MODE=true ;;
    --upgrade-secrets) UPGRADE_MODE=true; SECRETS_MODE=true ;;
    --help)    usage; exit 0 ;;
    *)
      error "Unknown option: $arg"
      usage
      exit 1
      ;;
  esac
done

# Conflict: --secrets and --swarm are mutually exclusive
if [ "$SECRETS_MODE" = "true" ] && [ "$SWARM_MODE" = "true" ] && [ "$UPGRADE_MODE" != "true" ]; then
  error "--secrets and --swarm are mutually exclusive."
  echo "  --secrets  writes secrets as local files (Compose)"
  echo "  --swarm    stores secrets in the Swarm Raft log (Swarm)"
  echo ""
  echo "Pick one based on your deployment:"
  echo "  Compose → ./${SCRIPT_NAME} --secrets"
  echo "  Swarm   → ./${SCRIPT_NAME} --swarm"
  exit 1
fi

# Conflict: --down is standalone
if [ "$DOWN_MODE" = "true" ]; then
  for _m in "$UP_MODE" "$BUILD_MODE" "$SECRETS_MODE" "$SWARM_MODE" "$UPGRADE_MODE"; do
    if [ "$_m" = "true" ]; then
      error "--down cannot be combined with other mode flags."
      exit 1
    fi
  done
fi

# Detect naked mode (no mode flags set)
_any_mode=false
for _m in "$CHECK_MODE" "$SECRETS_MODE" "$SWARM_MODE" "$BUILD_MODE" "$UP_MODE" "$UPGRADE_MODE" "$DOWN_MODE"; do
  [ "$_m" = "true" ] && _any_mode=true
done

# ---------------------------------------------------------------------------
# Check mode (--check) — read-only validation
# ---------------------------------------------------------------------------
# Validates .env has all required variables, checks for common issues,
# and reports shell env conflicts. Makes no changes.

if [ "$CHECK_MODE" = "true" ]; then
  header "Dungeon Master's Vault — Environment Check"

  if [ ! -f "$ENV_FILE" ]; then
    warn "No .env file found."
    echo "  1) Interactive setup (prompts for each value)"
    echo "  2) Auto setup (generates random passwords, safe defaults)"
    echo "  3) Skip"
    read -rp "Choice [1]: " _create || true
    case "${_create:-1}" in
      1) exec "$0" ;;
      2) exec "$0" --auto ;;
      *) exit 0 ;;
    esac
  fi

  ERRORS=0
  WARNING_MSGS=()
  ENV_CONFLICTS=()

  # Required variables — check .env first, then secrets/ files
  _has_secrets_dir=false
  [ -d "${SCRIPT_DIR}/secrets" ] && _has_secrets_dir=true

  for _var in DATOMIC_URL DATOMIC_PASSWORD ADMIN_PASSWORD SIGNATURE; do
    _val=$(read_env_val "$_var" "$ENV_FILE")
    if [ -n "$_val" ]; then
      info "  ${_var}: OK"
    elif [ "$_has_secrets_dir" = "true" ]; then
      # Map var names to secret file names
      case "$_var" in
        DATOMIC_PASSWORD) _secret_file="datomic_password" ;;
        ADMIN_PASSWORD)   _secret_file="admin_password" ;;
        SIGNATURE)        _secret_file="signature" ;;
        *)                _secret_file="" ;;
      esac
      if [ -n "$_secret_file" ] && [ -f "${SCRIPT_DIR}/secrets/${_secret_file}" ]; then
        info "  ${_var}: OK (via secrets/${_secret_file})"
      elif [ -n "$_secret_file" ] && docker secret inspect "$_secret_file" &>/dev/null; then
        info "  ${_var}: OK (via Swarm secret ${_secret_file})"
      else
        warn "  ${_var}: MISSING"
        WARNING_MSGS+=("${_var} is missing from .env")
        ERRORS=$((ERRORS + 1))
      fi
    else
      warn "  ${_var}: MISSING"
      WARNING_MSGS+=("${_var} is missing from .env")
      ERRORS=$((ERRORS + 1))
    fi
  done

  echo ""

  # URL health checks
  _url=$(read_env_val DATOMIC_URL "$ENV_FILE")
  if [[ "$_url" == *"password="* ]]; then
    warn "  DATOMIC_URL has embedded password (legacy format)"
    warn "  Run ./${SCRIPT_NAME} --upgrade to clean it"
    WARNING_MSGS+=("DATOMIC_URL has embedded password")
    ERRORS=$((ERRORS + 1))
  fi
  if [[ "$_url" == *"datomic:free://"* ]]; then
    warn "  DATOMIC_URL uses old Free protocol"
    warn "  Run ./${SCRIPT_NAME} --upgrade to convert to datomic:dev://"
    WARNING_MSGS+=("DATOMIC_URL uses Free protocol")
    ERRORS=$((ERRORS + 1))
  fi
  if [[ "$_url" == *"localhost"* ]]; then
    warn "  DATOMIC_URL contains 'localhost' (should be 'datomic' for Docker)"
    warn "  Run ./${SCRIPT_NAME} --upgrade to fix"
    WARNING_MSGS+=("DATOMIC_URL contains localhost")
    ERRORS=$((ERRORS + 1))
  fi

  echo ""

  # Shell env conflicts
  for _var in DATOMIC_URL DATOMIC_PASSWORD SIGNATURE ADMIN_PASSWORD; do
    check_env_conflict "$_var"
  done

  # Required files and directories
  echo ""
  check_file ".env"                "$ENV_FILE"
  check_file "docker-compose.yaml" "${SCRIPT_DIR}/docker-compose.yaml"
  check_file "nginx.conf.template" "${SCRIPT_DIR}/deploy/nginx.conf.template"
  check_dir  "data/"               "${SCRIPT_DIR}/data"
  check_dir  "logs/"               "${SCRIPT_DIR}/logs"

  echo ""
  if [ "$ERRORS" -eq 0 ]; then
    success "All checks passed"
  else
    warn "${ERRORS} issue(s) found."
    read -rp "Run upgrade to fix? [Y/n]: " _fix || true
    if [[ "${_fix,,}" =~ ^(y|)$ ]]; then
      exec "$0" --upgrade
    fi
  fi
  exit 0
fi

# ---------------------------------------------------------------------------
# Down mode (--down) — teardown running services
# ---------------------------------------------------------------------------

if [ "$DOWN_MODE" = "true" ]; then
  header "Dungeon Master's Vault — Teardown"

  _swarm_state=$(docker info --format '{{.Swarm.LocalNodeState}}' 2>/dev/null || true)

  if [ "$_swarm_state" = "active" ] && docker stack ls 2>/dev/null | grep -q orcpub; then
    info "Swarm stack detected."
    if confirm_action "Remove Swarm stack 'orcpub'?"; then
      docker stack rm orcpub 2>&1
      change "Swarm stack removed."
    fi
  elif docker compose ps -q 2>/dev/null | head -1 | grep -q .; then
    info "Compose services detected."
    if confirm_action "Tear down Compose services?"; then
      docker compose down 2>&1
      change "Compose services stopped."
    fi
  else
    info "No running services found."
  fi

  exit 0
fi

# ---------------------------------------------------------------------------
# Secrets migration (--secrets mode)
# ---------------------------------------------------------------------------
# Reads passwords from .env or shell environment and writes them as
# individual secret files. Works whether you use .env or export vars directly.
# Auto-generates docker-compose.secrets.yaml and wires it via COMPOSE_FILE.

if [ "$SECRETS_MODE" = "true" ] && [ "$UPGRADE_MODE" != "true" ]; then
  header "Dungeon Master's Vault — Secrets Migration"

  # Ask if they're running Swarm — different flow entirely
  if [ "${AUTO_MODE}" != "true" ]; then
    echo "This will create secret files on your machine (works with docker compose)."
    echo "If you're running Docker Swarm, secrets are stored in the cluster instead."
    echo ""
    read -rp "Are you using Docker Swarm? [y/N]: " _is_swarm || true
    if [[ "${_is_swarm,,}" == "y" ]]; then
      exec "$0" --swarm
    fi
  fi

  SECRETS_DIR="${SCRIPT_DIR}/secrets"

  # If no .env exists, generate one (enables one-step secrets setup)
  if [ ! -f "$ENV_FILE" ]; then
    generate_env
  fi

  read_passwords "--secrets"

  # Check for existing secrets (--auto implies --force here)
  if [ -d "$SECRETS_DIR" ] && [ "$FORCE_MODE" = "false" ] && [ "$AUTO_MODE" != "true" ]; then
    warn "secrets/ directory already exists. Use --force to overwrite."
    exit 1
  fi

  mkdir -p "$SECRETS_DIR"

  # Write each password to its own file (printf, not echo, to avoid trailing newline)
  printf '%s' "$_pw_datomic"   > "${SECRETS_DIR}/datomic_password" || { error "Failed to write ${SECRETS_DIR}/datomic_password"; exit 1; }
  printf '%s' "$_pw_admin"     > "${SECRETS_DIR}/admin_password"   || { error "Failed to write ${SECRETS_DIR}/admin_password"; exit 1; }
  printf '%s' "$_pw_signature" > "${SECRETS_DIR}/signature"        || { error "Failed to write ${SECRETS_DIR}/signature"; exit 1; }
  chmod 600 "${SECRETS_DIR}"/*

  change "Created secrets/datomic_password"
  change "Created secrets/admin_password"
  change "Created secrets/signature"
  change "File permissions set to 600"

  unset _pw_datomic _pw_admin _pw_signature

  # Generate compose override so secrets are wired in automatically
  write_compose_secrets "file"

  # Revert transactor host to compose-compatible binding if previously
  # switched to Swarm mode (host=0.0.0.0).
  switch_transactor_host "compose"

  # Move secret vars from .env to a backup file so they aren't duplicated
  BACKUP_FILE="${ENV_FILE}.secrets.backup"
  SECRET_VARS="DATOMIC_PASSWORD|ADMIN_PASSWORD|SIGNATURE"
  _moved=0
  if grep -qE "^(${SECRET_VARS})=" "$ENV_FILE" 2>/dev/null; then
    grep -E "^(${SECRET_VARS})=" "$ENV_FILE" >> "$BACKUP_FILE"
    sed -i -E "/^(${SECRET_VARS})=/d" "$ENV_FILE"
    _moved=1
  fi

  echo ""
  success "Done! Passwords are in secrets/, compose is configured."
  if [ "$_moved" -eq 1 ]; then
    change "Moved DATOMIC_PASSWORD, ADMIN_PASSWORD, SIGNATURE from .env to .env.secrets.backup"
    warn "Delete .env.secrets.backup after verifying secrets work."
  fi
  echo ""
  next "docker compose down && docker compose up -d"
  exit 0
fi

# ---------------------------------------------------------------------------
# Swarm secrets (--swarm mode)
# ---------------------------------------------------------------------------
# Creates Docker secrets via `docker secret create` for use in Swarm clusters.
# Secrets are stored encrypted in the Swarm Raft log and delivered to
# containers in memory — never written to disk on any node.

if [ "$SWARM_MODE" = "true" ] && [ "$UPGRADE_MODE" != "true" ]; then
  header "Dungeon Master's Vault — Swarm Secrets"

  # Check for running Compose containers — they'll conflict with Swarm networking
  _running=$(docker compose ps -q 2>/dev/null | head -1 || true)
  if [ -n "$_running" ]; then
    warn "Compose containers are running. These must be stopped before Swarm deploy."
    if confirm_action "Stop Compose services now?"; then
      docker compose down 2>&1 || true
      change "Compose services stopped."
    else
      warn "Swarm deploy will fail if Compose networks overlap. Continuing anyway..."
    fi
  fi

  # Verify this node is part of a Swarm — offer to initialize if not
  _swarm_state=$(docker info --format '{{.Swarm.LocalNodeState}}' 2>/dev/null || true)
  if [ "$_swarm_state" != "active" ]; then
    warn "This Docker node is not in Swarm mode."
    echo ""
    if confirm_action "Initialize a single-node Swarm now?"; then
      docker swarm init 2>&1 || { error "Failed to initialize Swarm."; exit 1; }
      change "Docker Swarm initialized."
    else
      info "Run 'docker swarm init' manually, then re-run: ./${SCRIPT_NAME} --swarm"
      exit 0
    fi
  fi

  # If no .env exists, generate one (enables one-step swarm setup)
  if [ ! -f "$ENV_FILE" ]; then
    generate_env
  fi

  read_passwords "--swarm"

  # Check for existing secrets and handle accordingly
  _existing=0
  _created=0

  for _name in datomic_password admin_password signature; do
    if docker secret inspect "$_name" &>/dev/null; then
      if [ "$FORCE_MODE" = "true" ]; then
        # Swarm doesn't support updating secrets — must remove and recreate.
        # Services using the secret must be stopped first.
        docker secret rm "$_name" &>/dev/null || true
        warn "Removed existing secret: $_name (--force)"
      else
        warn "Secret already exists: $_name (use --force to replace)"
        _existing=$((_existing + 1))
        continue
      fi
    fi

    # Get the right password value for this secret name
    case "$_name" in
      datomic_password) _val="$_pw_datomic" ;;
      admin_password)   _val="$_pw_admin" ;;
      signature)        _val="$_pw_signature" ;;
    esac

    if printf '%s' "$_val" | docker secret create "$_name" - 2>/dev/null; then
      change "Created Swarm secret: $_name"
      _created=$((_created + 1))
    else
      error "Failed to create Swarm secret: $_name"
      exit 1
    fi
  done

  unset _pw_datomic _pw_admin _pw_signature _val

  echo ""
  if [ "$_existing" -gt 0 ] && [ "$FORCE_MODE" = "false" ]; then
    warn "${_existing} secret(s) already existed (skipped)."
  fi
  if [ "$_created" -gt 0 ]; then
    change "${_created} Swarm secret(s) created."
  fi

  # Generate compose override so secrets are wired in automatically
  write_compose_secrets "external"

  # Switch transactor to Swarm-compatible host binding.
  switch_transactor_host "swarm"
  set_env_val ALT_HOST datomic "$ENV_FILE"
  change "ALT_HOST=datomic (peer fallback via Docker DNS)"

  echo ""
  success "Done! Swarm secrets created, compose is configured."

  # If --build or --up also specified, fall through to those blocks.
  if [ "$BUILD_MODE" != "true" ] && [ "$UP_MODE" != "true" ]; then
    echo ""
    echo "Next steps:"
    echo ""
    printf '  %sBUILD%s images:\n' "$color_cyan" "$color_reset"
    next "  ./${SCRIPT_NAME} --build"
    echo ""
    printf '  %sDEPLOY%s as a Swarm stack:\n' "$color_cyan" "$color_reset"
    next "  ./${SCRIPT_NAME} --up"
    echo ""
    info "Or both in one step: ./${SCRIPT_NAME} --build --up"
    echo ""
    echo "--- Tip: Managing secrets later ---"
    echo "  docker secret ls                     # List all secrets"
    echo "  docker secret inspect <name>         # Show metadata (not the value)"
    echo "  docker secret rm <name>              # Remove (stop services first)"
    exit 0
  fi
fi
# ---------------------------------------------------------------------------
# Build mode (--build) — build Docker images
# ---------------------------------------------------------------------------

if [ "$BUILD_MODE" = "true" ] && [ "$UP_MODE" != "true" ]; then
  header "Dungeon Master's Vault — Build"

  if ! docker compose version &>/dev/null; then
    error "docker compose is not available."
    exit 1
  fi

  if [ ! -f "$ENV_FILE" ]; then
    error "No .env file found."
    echo "  Run setup first:  ./${SCRIPT_NAME} [--auto]"
    if confirm_action "Run setup now?"; then
      generate_env
    else
      exit 1
    fi
  fi

  info "Building images..."
  docker compose build || { error "Build failed."; exit 1; }

  echo ""
  success "Images built!"
  exit 0
fi

# ---------------------------------------------------------------------------
# Up mode (--up) — deploy as a Docker Swarm stack
# ---------------------------------------------------------------------------

if [ "$UP_MODE" = "true" ]; then
  header "Dungeon Master's Vault — Swarm Deploy"

  if ! docker compose version &>/dev/null; then
    error "docker compose is not available."
    exit 1
  fi

  # Verify Swarm is active
  _swarm_state=$(docker info --format '{{.Swarm.LocalNodeState}}' 2>/dev/null || true)
  if [ "$_swarm_state" != "active" ]; then
    error "Docker Swarm is not active."
    echo ""
    echo "Options:"
    echo "  1) Initialize Swarm:  ./${SCRIPT_NAME} --swarm [--auto]"
    echo "  2) Use Compose instead: docker compose up --build -d"
    exit 1
  fi

  if [ ! -f "$ENV_FILE" ]; then
    error "No .env file found."
    echo "  Run setup first:  ./${SCRIPT_NAME} [--auto]"
    exit 1
  fi

  if ! command -v jq &>/dev/null; then
    error "jq is required for --up. Install it with: apt-get install jq"
    exit 1
  fi

  if [ "$BUILD_MODE" = "true" ]; then
    info "Building images..."
    docker compose build || { error "Build failed."; exit 1; }
    echo ""
  fi

  info "Deploying stack..."
  # docker compose config resolves ${VAR:-default} from shell env first, then
  # .env. Shell vars (e.g. Codespace DATOMIC_URL=localhost) override .env
  # values meant for Docker. Unset known conflicts so .env wins.
  _deploy_env=(DATOMIC_URL DATOMIC_PASSWORD SIGNATURE ADMIN_PASSWORD)
  for _v in "${_deploy_env[@]}"; do unset "$_v" 2>/dev/null || true; done

  # docker compose config outputs Compose Specification format;
  # docker stack deploy expects legacy v3 schema. JSON + jq bridges the gap.
  # See docs/kb/docker-swarm-compat.md for the full incompatibility list.
  docker compose config --format json | jq '
    del(.name) |
    .services |= with_entries(
      .value.depends_on |= (if type == "object" then keys else . end)
    ) |
    .services |= with_entries(
      .value.ports |= (if . then [.[] | .published |= tonumber] else . end)
    ) |
    # Strip explicit nulls last — Swarm rejects null entrypoint/command/ports
    # and |= on missing keys re-creates them as null
    .services |= with_entries(
      .value |= with_entries(select(.value != null))
    )
  ' | docker stack deploy -c - orcpub || { error "Deploy failed."; exit 1; }

  echo ""
  success "Stack deployed!"
  echo ""
  echo "Useful commands:"
  echo "  docker stack services orcpub    # List services"
  echo "  docker stack ps orcpub          # List tasks"
  echo "  docker service logs <service>   # View logs"
  exit 0
fi


# ---------------------------------------------------------------------------
# Upgrade existing .env (--upgrade mode)
# ---------------------------------------------------------------------------
# Reads the current .env, detects old patterns, fixes them, adds missing
# variables. Backs up the original first. No data loss.

if [ "$UPGRADE_MODE" = "true" ]; then
  header "Dungeon Master's Vault — Upgrade .env"

  if [ ! -f "$ENV_FILE" ]; then
    warn "No .env file found."
    info "Scanning config files for hardcoded values..."

    _compose="${SCRIPT_DIR}/docker-compose.yaml"
    _transactor="${SCRIPT_DIR}/deploy/transactor.properties"
    _found=0

    # Declare associative arrays for values from each source
    declare -A _compose_vals _transactor_vals

    # Scan docker-compose.yaml for hardcoded values (not ${...} templated)
    if [ -f "$_compose" ]; then
      for _var in DATOMIC_URL DATOMIC_PASSWORD ADMIN_PASSWORD SIGNATURE; do
        _val=$(grep -E "^\s+${_var}:" "$_compose" | head -1 | sed "s/^[[:space:]]*${_var}: *//" | tr -d '\r')
        # shellcheck disable=SC2016  # Intentional: checking for literal '${' prefix
        if [ -n "$_val" ] && [ "${_val#'${'}" = "$_val" ]; then
          _compose_vals[$_var]="$_val"
        fi
      done
    fi

    # Scan deploy/transactor.properties for hardcoded passwords (not ${...} templated)
    if [ -f "$_transactor" ]; then
      for _prop in "storage-admin-password:ADMIN_PASSWORD" "storage-datomic-password:DATOMIC_PASSWORD"; do
        _key="${_prop%%:*}"
        _var="${_prop##*:}"
        _val=$(grep -E "^${_key}=" "$_transactor" | head -1 | sed 's/.*=//' | tr -d '\r')
        # shellcheck disable=SC2016  # Intentional: checking for literal '${' prefix
        if [ -n "$_val" ] && [ "${_val#'${'}" = "$_val" ]; then
          _transactor_vals[$_var]="$_val"
        fi
      done
    fi

    # Build .env, checking for conflicts between sources
    for _var in DATOMIC_URL DATOMIC_PASSWORD ADMIN_PASSWORD SIGNATURE; do
      _cv="${_compose_vals[$_var]:-}"
      _tv="${_transactor_vals[$_var]:-}"

      if [ -n "$_cv" ] && [ -n "$_tv" ] && [ "$_cv" != "$_tv" ]; then
        echo ""
        warn "  ${_var}: CONFLICT between docker-compose.yaml and transactor.properties"
        warn "    1) compose:    ${_cv}"
        warn "    2) transactor: ${_tv}"
        if [ "${AUTO_MODE}" = "true" ]; then
          warn "    Using transactor value (that's what the database is actually using)"
          echo "${_var}=${_tv}" >> "$ENV_FILE"
        else
          read -rp "    Use which? [1] compose  [2] transactor (recommended): " _choice || true
          if [ "$_choice" = "1" ]; then
            echo "${_var}=${_cv}" >> "$ENV_FILE"
            change "  Using compose value for ${_var}"
          else
            echo "${_var}=${_tv}" >> "$ENV_FILE"
            change "  Using transactor value for ${_var}"
          fi
        fi
        _found=$((_found + 1))
      elif [ -n "$_tv" ]; then
        echo "${_var}=${_tv}" >> "$ENV_FILE"
        change "  Found ${_var} in transactor.properties"
        _found=$((_found + 1))
      elif [ -n "$_cv" ]; then
        echo "${_var}=${_cv}" >> "$ENV_FILE"
        change "  Found ${_var} in docker-compose.yaml"
        _found=$((_found + 1))
      fi
    done

    if [ "$_found" -eq 0 ]; then
      error "No hardcoded values found in docker-compose.yaml or transactor.properties."
      error "For a new install, run: ./${SCRIPT_NAME} --auto"
      exit 1
    fi

    chmod 600 "$ENV_FILE"
    change "Created .env with ${_found} value(s) extracted from config files"
    info "Continuing with upgrade to fill any gaps..."
    echo ""
  fi

  CHANGES=0
  BACKUP="${ENV_FILE}.backup.$(date +%s)"
  cp "$ENV_FILE" "$BACKUP"
  info "Backed up .env to $(basename "$BACKUP")"

  # Load current values
  source_env "$ENV_FILE"

  _url=$(read_env_val DATOMIC_URL "$ENV_FILE")
  _pw=$(read_env_val DATOMIC_PASSWORD "$ENV_FILE")
  _sig=$(read_env_val SIGNATURE "$ENV_FILE")
  _admin=$(read_env_val ADMIN_PASSWORD "$ENV_FILE")

  echo ""

  # --- Check 1: Password embedded in DATOMIC_URL ---
  if [[ "$_url" == *"password="* ]]; then
    # Extract password from URL
    _url_pw=$(echo "$_url" | sed -n 's/.*[?&]password=\([^&]*\).*/\1/p')
    # shellcheck disable=SC2001  # Regex too complex for parameter expansion
    _clean_url=$(echo "$_url" | sed 's/[?&]password=[^&]*//')

    if [ -n "$_url_pw" ]; then
      change "Found password embedded in DATOMIC_URL — extracting"

      # If DATOMIC_PASSWORD exists and differs, warn
      if [ -n "$_pw" ] && [ "$_pw" != "$_url_pw" ]; then
        warn "  DATOMIC_PASSWORD in .env differs from URL password!"
        warn "  Using the URL password (that's what the transactor is using)"
      fi

      # Update the file
      set_env_val DATOMIC_URL "$_clean_url" "$ENV_FILE"
      set_env_val DATOMIC_PASSWORD "$_url_pw" "$ENV_FILE"
      CHANGES=$((CHANGES + 1))
      change "  DATOMIC_URL: password removed"
      change "  DATOMIC_PASSWORD: set to extracted password"
    fi
  else
    info "DATOMIC_URL: OK (no embedded password)"
  fi

  # --- Check 2: Missing DATOMIC_PASSWORD ---
  if [ -z "$_pw" ] && ! grep -q '^DATOMIC_PASSWORD=' "$ENV_FILE"; then
    if [ "${AUTO_MODE}" = "true" ]; then
      _new_pw="$(generate_password 24)"
      set_env_val DATOMIC_PASSWORD "$_new_pw" "$ENV_FILE"
      CHANGES=$((CHANGES + 1))
      change "  Generated new DATOMIC_PASSWORD (random)"
      warn "  IMPORTANT: Update your transactor to use this password too!"
    else
      warn "  DATOMIC_PASSWORD is missing."
      warn "  This should match what your transactor uses."
      read -rp "  Generate a random one? [Y/n]: " _gen || true
      if [[ "${_gen,,}" =~ ^(y|)$ ]]; then
        _new_pw="$(generate_password 24)"
        set_env_val DATOMIC_PASSWORD "$_new_pw" "$ENV_FILE"
        CHANGES=$((CHANGES + 1))
        change "  Generated new DATOMIC_PASSWORD (random)"
        warn "  IMPORTANT: Update your transactor to use this password too!"
      fi
    fi
  else
    info "DATOMIC_PASSWORD: OK"
  fi

  # --- Check 3: Missing SIGNATURE ---
  if [ -z "$_sig" ] && ! grep -q '^SIGNATURE=' "$ENV_FILE"; then
    if [ "${AUTO_MODE}" = "true" ]; then
      _new_sig="$(generate_password 32)"
      set_env_val SIGNATURE "$_new_sig" "$ENV_FILE"
      CHANGES=$((CHANGES + 1))
      change "  Generated new SIGNATURE (random)"
      warn "  Note: Changing this later will log out all active users."
    else
      warn "  SIGNATURE is missing (needed for login/API)."
      read -rp "  Generate a random one? [Y/n]: " _gen || true
      if [[ "${_gen,,}" =~ ^(y|)$ ]]; then
        _new_sig="$(generate_password 32)"
        set_env_val SIGNATURE "$_new_sig" "$ENV_FILE"
        CHANGES=$((CHANGES + 1))
        change "  Generated new SIGNATURE (random)"
        warn "  Note: Changing this later will log out all active users."
      fi
    fi
  else
    info "SIGNATURE: OK"
  fi

  # --- Check 4: Missing ADMIN_PASSWORD ---
  if [ -z "$_admin" ] && ! grep -q '^ADMIN_PASSWORD=' "$ENV_FILE"; then
    if [ "${AUTO_MODE}" = "true" ]; then
      _new_admin="$(generate_password 24)"
      set_env_val ADMIN_PASSWORD "$_new_admin" "$ENV_FILE"
      CHANGES=$((CHANGES + 1))
      change "  Generated new ADMIN_PASSWORD (random)"
    else
      warn "  ADMIN_PASSWORD is missing."
      read -rp "  Generate a random one? [Y/n]: " _gen || true
      if [[ "${_gen,,}" =~ ^(y|)$ ]]; then
        _new_admin="$(generate_password 24)"
        set_env_val ADMIN_PASSWORD "$_new_admin" "$ENV_FILE"
        CHANGES=$((CHANGES + 1))
        change "  Generated new ADMIN_PASSWORD (random)"
      fi
    fi
  else
    info "ADMIN_PASSWORD: OK"
  fi

  # --- Check 5: Old Free protocol → upgrade to dev ---
  # Re-read URL after password extraction may have changed it
  _url=$(read_env_val DATOMIC_URL "$ENV_FILE")

  if [[ "$_url" == *"datomic:free://"* ]]; then
    _new_url="${_url/datomic:free:\/\//datomic:dev:\/\/}"
    set_env_val DATOMIC_URL "$_new_url" "$ENV_FILE"
    CHANGES=$((CHANGES + 1))
    change "  Changed datomic:free:// to datomic:dev:// (Datomic Pro)"
    warn "  If you have existing Free data, migrate it:"
    warn "    1. Back up first:  ./docker-migrate.sh backup"
    warn "    2. Rebuild:        docker compose up --build -d"
    warn "    3. Restore:        ./docker-migrate.sh restore"
    warn "  See docs/migration/datomic-data-migration.md for the full guide."
    # Update for Check 6
    _url="$_new_url"
  fi

  # --- Check 6: localhost → datomic (Docker service name) ---
  if [[ "$_url" == *"localhost"* ]]; then
    _new_url="${_url//localhost/datomic}"
    set_env_val DATOMIC_URL "$_new_url" "$ENV_FILE"
    CHANGES=$((CHANGES + 1))
    change "  Changed 'localhost' to 'datomic' (Docker service name)"
  fi

  # --- Check 7: Image tags (ORCPUB_IMAGE / DATOMIC_IMAGE) ---
  _orcpub_img=$(read_env_val ORCPUB_IMAGE "$ENV_FILE")
  _datomic_img=$(read_env_val DATOMIC_IMAGE "$ENV_FILE")
  if [ -z "$_orcpub_img" ] && [ -z "$_datomic_img" ]; then
    if [ "${AUTO_MODE}" != "true" ]; then
      echo ""
      info "No image tags set (builds use default names: orcpub-app, orcpub-datomic)"
      _tag=$(prompt_value "Image tag to version your builds (leave empty to skip)" "")
      if [ -n "$_tag" ]; then
        set_env_val ORCPUB_IMAGE "orcpub-app:${_tag}" "$ENV_FILE"
        set_env_val DATOMIC_IMAGE "orcpub-datomic:${_tag}" "$ENV_FILE"
        CHANGES=$((CHANGES + 2))
        change "  Set ORCPUB_IMAGE=orcpub-app:${_tag}"
        change "  Set DATOMIC_IMAGE=orcpub-datomic:${_tag}"
      fi
    fi
  else
    if [ "${AUTO_MODE}" != "true" ]; then
      # Extract current tag from image name (e.g. "orcpub-app:v2.6" → "v2.6")
      _current_tag="${_orcpub_img##*:}"
      [ "$_current_tag" = "$_orcpub_img" ] && _current_tag=""
      info "ORCPUB_IMAGE: ${_orcpub_img}"
      info "DATOMIC_IMAGE: ${_datomic_img}"
      _tag=$(prompt_value "Image tag" "${_current_tag}")
      if [ -n "$_tag" ] && [ "$_tag" != "$_current_tag" ]; then
        # Preserve base name, update tag
        _orcpub_base="${_orcpub_img%%:*}"
        _datomic_base="${_datomic_img%%:*}"
        set_env_val ORCPUB_IMAGE "${_orcpub_base}:${_tag}" "$ENV_FILE"
        set_env_val DATOMIC_IMAGE "${_datomic_base}:${_tag}" "$ENV_FILE"
        CHANGES=$((CHANGES + 2))
        change "  Set ORCPUB_IMAGE=${_orcpub_base}:${_tag}"
        change "  Set DATOMIC_IMAGE=${_datomic_base}:${_tag}"
      else
        info "  Image tags unchanged."
      fi
    else
      info "ORCPUB_IMAGE: ${_orcpub_img}"
      info "DATOMIC_IMAGE: ${_datomic_img}"
    fi
  fi

  echo ""
  if [ "$CHANGES" -gt 0 ]; then
    change "${CHANGES} change(s) applied to .env"
  else
    info "No changes needed — .env is already up to date."
  fi
  info "Backup saved: $(basename "$BACKUP")"

  # --- Chain into secrets if combined (--upgrade-swarm / --upgrade-secrets) ---
  if [ "$SWARM_MODE" = "true" ]; then
    echo ""
    info "Continuing to Swarm secrets setup..."
    if [ "${AUTO_MODE}" = "true" ]; then
      exec "$0" --swarm --auto
    else
      exec "$0" --swarm
    fi
  elif [ "$SECRETS_MODE" = "true" ]; then
    echo ""
    info "Continuing to secrets setup..."
    if [ "${AUTO_MODE}" = "true" ]; then
      exec "$0" --secrets --auto
    else
      exec "$0" --secrets
    fi
  fi

  # Standalone --upgrade: offer secrets interactively
  if [ ! -d "${SCRIPT_DIR}/secrets" ]; then
    echo ""
    if [ "${AUTO_MODE}" = "true" ]; then
      info "Tip: Run ./${SCRIPT_NAME} --upgrade-secrets or --upgrade-swarm to also"
      info "     move passwords out of .env in one step."
    else
      echo ""
      read -rp "Move passwords to Docker secret files? (more secure) [y/N]: " _do_secrets || true
      if [[ "${_do_secrets,,}" == "y" ]]; then
        exec "$0" --secrets
      fi
    fi
  else
    info "Docker secrets: already configured (secrets/ exists)"
  fi

  # Detect shell/env conflicts for the launch command
  ENV_CONFLICTS=()
  WARNING_MSGS=()
  ERRORS=0
  for _var in DATOMIC_URL DATOMIC_PASSWORD SIGNATURE ADMIN_PASSWORD; do
    check_env_conflict "$_var"
  done

  echo ""
  next "$(build_compose_cmd "docker compose up -d")"
  exit 0
fi

# ---------------------------------------------------------------------------
# Main — setup, validate, and (in naked mode) build + start
# ---------------------------------------------------------------------------

if [ "$_any_mode" = "false" ]; then
  header "Dungeon Master's Vault — Full Setup & Deploy"
else
  header "Dungeon Master's Vault — Docker Setup"
fi

# ---- Step 1: .env file ---------------------------------------------------

if [ -f "$ENV_FILE" ] && [ "$FORCE_MODE" = "false" ]; then
  info "Existing .env file found. Skipping generation (use --force to overwrite)."
else
  # Source existing .env (if any) so current values become defaults for prompts
  if [ -f "$ENV_FILE" ]; then
    source_env "$ENV_FILE"
  fi

  generate_env
fi

# ---- Step 2: Validation --------------------------------------------------

header "Validation"

ERRORS=0
WARNING_MSGS=()
ENV_CONFLICTS=()

# Validate DATOMIC_PASSWORD vs DATOMIC_URL
if [ -f "$ENV_FILE" ]; then
  _env_datomic_pw=$(read_env_val DATOMIC_PASSWORD "$ENV_FILE")
  _env_datomic_url=$(read_env_val DATOMIC_URL "$ENV_FILE")
  if [ -n "$_env_datomic_pw" ] && [ -n "$_env_datomic_url" ]; then
    if [[ "$_env_datomic_url" == *"password="* ]]; then
      # Legacy: password embedded in URL — check it matches DATOMIC_PASSWORD
      if [[ "$_env_datomic_url" != *"password=${_env_datomic_pw}"* ]]; then
        warn "  DATOMIC_URL has an embedded password that doesn't match DATOMIC_PASSWORD"
        warn "  Remove ?password= from DATOMIC_URL — the app adds it from DATOMIC_PASSWORD automatically"
        WARNING_MSGS+=("DATOMIC_URL embedded password doesn't match DATOMIC_PASSWORD")
        ERRORS=$((ERRORS + 1))
      else
        info "  DATOMIC_URL password: OK (embedded — consider removing ?password= from URL)"
      fi
    else
      # Modern: password separate — the app appends it at startup
      info "  DATOMIC_PASSWORD: OK (app will append to URL at startup)"
    fi
  fi
  unset _env_datomic_pw _env_datomic_url
fi

if [ -f "$ENV_FILE" ]; then
  check_env_conflict DATOMIC_URL
  check_env_conflict SIGNATURE
  check_env_conflict ADMIN_PASSWORD
  check_env_conflict DATOMIC_PASSWORD
fi

check_file ".env"                "$ENV_FILE"
check_file "docker-compose.yaml" "${SCRIPT_DIR}/docker-compose.yaml"
check_file "nginx.conf.template" "${SCRIPT_DIR}/deploy/nginx.conf.template"
check_file "SSL certificate"     "${SCRIPT_DIR}/deploy/snakeoil.crt"
check_file "SSL key"             "${SCRIPT_DIR}/deploy/snakeoil.key"
check_dir  "data/"               "${SCRIPT_DIR}/data"
check_dir  "logs/"               "${SCRIPT_DIR}/logs"
check_dir  "backups/"            "${SCRIPT_DIR}/backups"
check_dir  "deploy/homebrew/"    "${SCRIPT_DIR}/deploy/homebrew"

echo ""

if [ "$ERRORS" -gt 0 ]; then
  warn "Setup completed with ${ERRORS} warning(s). Review the items above."
else
  success "All checks passed!"
fi

# ---- Step 3: Build + Start (naked mode only) --------------------------------

if [ "$_any_mode" = "false" ]; then

  # Build
  if confirm_action "Build Docker images?"; then
    info "Building images..."
    docker compose build || { error "Build failed."; exit 1; }
    echo ""
    success "Images built successfully."
  else
    info "Skipping build."
  fi

  # Start
  if confirm_action "Start services?"; then
    COMPOSE_CMD=$(build_compose_cmd "docker compose up -d")
    info "Starting services..."
    eval "$COMPOSE_CMD" || { error "Failed to start services."; exit 1; }
    echo ""
    success "Services started."
    echo ""
    echo "Wait for healthy (app takes ~2 minutes to boot):"
    echo "  docker compose ps"
    echo ""
    echo "Create your first user:"
    echo "  ./docker-user.sh init                                 # uses INIT_ADMIN_* from .env"
    echo "  ./docker-user.sh create <username> <email> <password>  # or specify directly"
    echo ""
    echo "Access the site at:"
    echo "  https://localhost"
  else
    info "Skipping start."
    COMPOSE_CMD=$(build_compose_cmd "docker compose up --build -d")
    echo ""
    echo "To start manually:"
    printf '  %s\n' "$COMPOSE_CMD"
  fi

else

  # ---- Upgrade fall-through: show next steps only ----------------------------

  header "Next Steps"

  COMPOSE_CMD=$(build_compose_cmd "docker compose up --build -d")

  cat <<NEXT
1. Review your .env file and adjust values if needed.

2. Build and launch:
     ${COMPOSE_CMD}

   First build takes ~10 minutes. Subsequent builds use cache.

3. Wait for healthy (app takes ~2 minutes to boot):
     docker compose ps

4. Create your first user (once all services show "healthy"):
     ./docker-user.sh init                                 # uses INIT_ADMIN_* from .env
     ./docker-user.sh create <username> <email> <password>  # or specify directly

5. Access the site at:
     https://localhost

6. Manage users later with:
     ./docker-user.sh list              # List all users
     ./docker-user.sh check <user>      # Check a user's status
     ./docker-user.sh verify <user>     # Verify an unverified user

7. To import homebrew content, place your .orcbrew file at:
     deploy/homebrew/homebrew.orcbrew

For more details, see docs/DOCKER.md
NEXT

fi

# ---- Final status banner ----------------------------------------------------

echo ""
if [ "$ERRORS" -gt 0 ]; then
  printf '%s!!! %d WARNING(S) — review before starting !!!%s\n' "$color_yellow" "$ERRORS" "$color_reset"
  for msg in "${WARNING_MSGS[@]}"; do
    printf '  %s• %s%s\n' "$color_yellow" "$msg" "$color_reset"
  done
  if [ "${#ENV_CONFLICTS[@]}" -gt 0 ]; then
    echo ""
    printf '  %sTo launch with .env values:%s\n' "$color_cyan" "$color_reset"
    printf '    %s\n' "$COMPOSE_CMD"
  fi
  echo ""
else
  success "SUCCESS — ready to launch"
  if [ "$_any_mode" = "true" ]; then
    printf '  %s\n' "$COMPOSE_CMD"
  fi
  echo ""
fi