vox

#!/usr/bin/env bash
set -euo pipefail

# ─────────────────────────────────────────────────────────────────────────────
# vox — Multi-Command Deploy CLI: Any Repo → Docker + Cloudflare Tunnel
# ─────────────────────────────────────────────────────────────────────────────
# Usage:
#   ./vox setup          # Interactive first-time setup
#   ./vox setup --repo URL --token TOKEN --hostname DOMAIN [--env .env] [--branch main]
#   ./vox deploy         # Pull latest + rebuild + zero-downtime restart
#   ./vox logs [--follow]# Tail container logs
#   ./vox status         # Show running containers, health, uptime
#   ./vox stop           # Stop all services
#   ./vox start          # Start services
#   ./vox restart        # Restart services
#   ./vox rollback [n]   # Roll back to previous deploy
#   ./vox env            # Show current env vars (masked secrets)
#   ./vox env set K=V    # Set an env var and redeploy
#   ./vox env unset K    # Remove an env var and redeploy
#   ./vox destroy        # Tear down everything
#   ./vox history        # Show deploy history
#   ./vox watch                  # Start auto-redeploy watcher (fg-detached)
#   ./vox watch stop|status      # Manage the watcher
#   ./vox watch logs [--follow]  # Tail the watcher log
#   ./vox watch once             # One fetch + deploy-if-needed (cron/webhook)
#   ./vox watch install-service  # systemd unit so watcher survives reboots
#   ./vox help           # Show usage
# ─────────────────────────────────────────────────────────────────────────────

BOLD='\033[1m'
DIM='\033[2m'
GREEN='\033[0;32m'
CYAN='\033[0;36m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
MAGENTA='\033[0;35m'
NC='\033[0m'

# ─────────────────────────────────────────────────────────────────────────────
# BUILDKIT / COMPOSE STREAMING — force real-time, line-by-line output
# ─────────────────────────────────────────────────────────────────────────────
# Without these, `docker compose build` uses BuildKit's fancy TTY progress
# mode which buffers everything and surfaces nothing until the user interrupts.
# Symptom: "Building container..." followed by a silent spinner that only
# dumps output after Ctrl+C.
#
# Setting BUILDKIT_PROGRESS=plain + passing --progress=plain forces every
# buildkit stage to flush its stdout/stderr line-by-line so users see each
# layer, RUN step, and warning in real time.
export DOCKER_BUILDKIT="${DOCKER_BUILDKIT:-1}"
export COMPOSE_DOCKER_CLI_BUILD="${COMPOSE_DOCKER_CLI_BUILD:-1}"
export BUILDKIT_PROGRESS="${BUILDKIT_PROGRESS:-plain}"
# Line-buffer python subprocesses too (vox_save_config, vox_config_get, etc.)
export PYTHONUNBUFFERED="${PYTHONUNBUFFERED:-1}"

get_cols() { tput cols 2>/dev/null || echo 80; }

banner() {
  local cols
  cols=$(get_cols)
  local inner=$((cols - 4))
  [[ "$inner" -lt 20 ]] && inner=20
  local hbar=""
  for ((i=0; i<inner+2; i++)); do hbar="${hbar}─"; done

  local text="$1"
  local plain_text
  plain_text=$(echo -e "$text" | sed 's/\x1b\[[0-9;]*m//g')
  local tlen=${#plain_text}
  local pad=$((inner - tlen))
  [[ "$pad" -lt 0 ]] && pad=0
  local spaces=""
  for ((i=0; i<pad; i++)); do spaces="${spaces} "; done

  echo ""
  echo -e "${CYAN}╭${hbar}╮${NC}"
  echo -e "${CYAN}│${NC} ${BOLD}${text}${NC}${spaces} ${CYAN}│${NC}"
  echo -e "${CYAN}╰${hbar}╯${NC}"
  echo ""
}

info()    { echo -e "  ${GREEN}[INFO]${NC}  $1"; }
warn()    { echo -e "  ${YELLOW}[WARN]${NC}  $1"; }
err()     { echo -e "  ${RED}[ERR]${NC}  $1"; }
detect()  { echo -e "  ${MAGENTA}[AUTO]${NC}  $1"; }
step()    { echo -e "  ${CYAN}[STEP]${NC}  $1"; }
prompt()  { echo -en "${BOLD}$1${NC}"; }

# ─────────────────────────────────────────────────────────────────────────────
# STREAMING WRAPPERS — surface real-time state during long-running subprocesses
# ─────────────────────────────────────────────────────────────────────────────
# These wrap slow docker operations so the user sees every line of output as
# it happens instead of a silent spinner. They also mirror output to a log
# file for post-mortem review and return the child process's real exit code
# (not `tee`'s) via PIPESTATUS.

stream_open() {
  local label="${1:-output}"
  local cols inner hbar
  cols=$(get_cols)
  inner=$((cols - 8 - ${#label}))
  [[ "$inner" -lt 10 ]] && inner=10
  hbar=""
  for ((i=0; i<inner; i++)); do hbar="${hbar}─"; done
  echo ""
  echo -e "  ${DIM}┌─ ${label} ${hbar}${NC}"
}

stream_close() {
  local status="${1:-done}"
  local color="${2:-$DIM}"
  local cols inner hbar
  cols=$(get_cols)
  inner=$((cols - 8 - ${#status}))
  [[ "$inner" -lt 10 ]] && inner=10
  hbar=""
  for ((i=0; i<inner; i++)); do hbar="${hbar}─"; done
  echo -e "  ${DIM}└─${NC} ${color}${status}${NC} ${DIM}${hbar}${NC}"
  echo ""
}

# Pick the right --progress flag style based on compose version.
# docker compose v2 supports --progress=plain on `build`; docker-compose v1
# does not, so for v1 we rely on the BUILDKIT_PROGRESS=plain env var alone.
_compose_progress_flag() {
  if [[ "${COMPOSE_CMD:-docker compose}" == "docker compose" ]]; then
    echo "--progress=plain"
  else
    echo ""
  fi
}

# Ensure VOX_DIR exists before writing logs (works even before setup runs).
_ensure_log_dir() {
  local d="${VOX_DIR:-.vox}"
  mkdir -p "$d" 2>/dev/null || true
  echo "$d"
}

# compose_build [extra-args...] — run `docker compose build` with streaming
# output, a mirrored log file, and a proper exit code.
compose_build() {
  local log_dir build_log progress_flag
  log_dir=$(_ensure_log_dir)
  build_log="$log_dir/build.log"
  progress_flag=$(_compose_progress_flag)

  info "Building container image (streaming output below, log: $build_log)"
  stream_open "docker compose build"

  # 2>&1  → merge stderr into stdout (buildkit writes progress to stderr)
  # tee   → mirror to build log for post-mortem inspection
  # PIPESTATUS → return the real build exit code, not tee's
  set +e
  if [[ -n "$progress_flag" ]]; then
    $COMPOSE_CMD build $progress_flag "$@" 2>&1 | tee "$build_log"
  else
    $COMPOSE_CMD build "$@" 2>&1 | tee "$build_log"
  fi
  local rc=${PIPESTATUS[0]}
  set -e

  if [[ "$rc" -eq 0 ]]; then
    stream_close "build ok" "$GREEN"
  else
    stream_close "build FAILED (exit $rc)" "$RED"
    err "Build failed — full log at $build_log"
  fi
  return "$rc"
}

# compose_up [extra-args...] — run `docker compose up -d` with streaming
# output so the user sees network/volume/container creation in real time.
compose_up() {
  info "Starting services (streaming output below)"
  stream_open "docker compose up -d"
  set +e
  local output
  output=$($COMPOSE_CMD up -d --remove-orphans "$@" 2>&1)
  local rc=$?
  echo "$output"
  set -e
  # Handle container name conflict from a stale/orphaned container
  if [[ "$rc" -ne 0 ]] && echo "$output" | grep -q 'Conflict.*container name.*already in use'; then
    local stale_id
    stale_id=$(echo "$output" | grep -oP 'already in use by container "\K[a-f0-9]+' | head -1)
    if [[ -n "$stale_id" ]]; then
      warn "Removing stale container $stale_id from a previous project"
      docker rm -f "$stale_id" 2>/dev/null || true
      set +e
      $COMPOSE_CMD up -d --remove-orphans "$@" 2>&1
      rc=$?
      set -e
    fi
  fi
  if [[ "$rc" -ne 0 ]] && echo "$output" | grep -qiE 'address already in use|port is already allocated|bind.*failed|listen EADDRINUSE'; then
    warn "A tracked port appears occupied; releasing this vox project's stale containers and retrying once"
    compose_release_project_resources
    set +e
    $COMPOSE_CMD up -d --remove-orphans "$@" 2>&1
    rc=$?
    set -e
  fi
  if [[ "$rc" -eq 0 ]]; then
    stream_close "up ok" "$GREEN"
  else
    stream_close "up FAILED (exit $rc)" "$RED"
  fi
  return "$rc"
}

# compose_down [extra-args...] — streamed `docker compose down` for symmetry.
compose_down() {
  info "Stopping services (streaming output below)"
  stream_open "docker compose down"
  set +e
  $COMPOSE_CMD down --remove-orphans "$@" 2>&1
  local rc=$?
  set -e
  if [[ "$rc" -eq 0 ]]; then
    stream_close "down ok" "$GREEN"
  else
    stream_close "down FAILED (exit $rc)" "$RED"
  fi
  return "$rc"
}

compose_project_name() {
  local dir
  dir="${WORK_DIR:-$(pwd)}"
  basename "$dir" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_-' '-'
}

compose_release_project_resources() {
  local project
  project="$(compose_project_name)"

  set +e
  $COMPOSE_CMD down --remove-orphans --timeout 20 >/dev/null 2>&1
  docker ps -aq \
    --filter "label=com.docker.compose.project=${project}" \
    --filter "status=exited" \
    --filter "status=created" \
    --filter "status=dead" \
    | xargs -r docker rm -f >/dev/null 2>&1
  set -e
}

# ─────────────────────────────────────────────────────────────────────────────
# INSTALL HELPERS — run install_cmd when lockfiles change (package updates)
# ─────────────────────────────────────────────────────────────────────────────

# Hash a lockfile (or empty string if missing) for change detection.
hash_lockfile() {
  local f="$1"
  if [[ -f "$f" ]]; then
    sha256sum "$f" 2>/dev/null | awk '{print $1}' || true
  fi
}

# Run the project's install command if lockfiles have changed since last deploy.
# Returns 0 on success or when skipped, 1 on failure.
run_install_if_needed() {
  local repo_path="$1"
  local install_cmd="$2"
  local force="${3:-}"

  if [[ -z "$install_cmd" ]]; then
    return 0
  fi

  local hash_file="$VOX_DIR/last-install-hash"
  local current_hash=""

  # Detect lockfiles in priority order
  local lockfiles=(
    "$repo_path/package-lock.json"
    "$repo_path/pnpm-lock.yaml"
    "$repo_path/yarn.lock"
    "$repo_path/bun.lockb"
    "$repo_path/bun.lock"
    "$repo_path/Cargo.lock"
    "$repo_path/Pipfile.lock"
    "$repo_path/poetry.lock"
    "$repo_path/go.sum"
    "$repo_path/Gemfile.lock"
    "$repo_path/composer.lock"
  )

  for lf in "${lockfiles[@]}"; do
    if [[ -f "$lf" ]]; then
      current_hash="${current_hash}$(hash_lockfile "$lf")"
    fi
  done

  local last_hash=""
  if [[ -f "$hash_file" ]]; then
    last_hash=$(cat "$hash_file" 2>/dev/null || true)
  fi

  if [[ "$force" == "force" ]] || [[ "$current_hash" != "$last_hash" ]]; then
    info "Lockfile change detected — running install command..."
    info "  $install_cmd"
    set +e
    (cd "$repo_path" && eval "$install_cmd")
    local rc=$?
    set -e
    if [[ "$rc" -eq 0 ]]; then
      echo "$current_hash" > "$hash_file"
      info "Install completed successfully"
      return 0
    else
      err "Install command failed (exit $rc)"
      return 1
    fi
  fi

  return 0
}
# `sudo` writes its password prompt to /dev/tty by default, so redirecting
# stderr to /dev/null does NOT hide the prompt — but it DOES hide every other
# diagnostic, which made earlier silent hangs impossible to debug. We split
# "is sudo available without a password" from "actually run a privileged
# command" and put a hard timeout on every privileged call so an unattended
# auto-deploy can never block on a missing password.
# ─────────────────────────────────────────────────────────────────────────────

SUDO_OK=""   # "yes" once we know sudo works (cached or root); "no" if unavailable

# Wrap a command in `timeout` if the binary exists; otherwise run it bare.
with_timeout() {
  local secs="$1"; shift
  if command -v timeout &>/dev/null; then
    timeout --foreground "$secs" "$@"
  else
    "$@"
  fi
}

# ─────────────────────────────────────────────────────────────────────────────
# DOCKER PREFLIGHT — fail loudly and fast when the daemon is wedged
# ─────────────────────────────────────────────────────────────────────────────
# Background: on systems with Docker's data root on ZFS + overlay2 storage
# driver, `dockerd` can deadlock in the kernel during container cleanup and
# get stuck in D-state. Once that happens, every `docker` command will hang
# for its full RPC timeout (2+ minutes) before returning. We refuse to let
# vox inherit that pain: a 5-second probe tells us immediately whether the
# daemon is alive, and if it isn't we print the exact remediation steps and
# exit instead of silently hanging forever.
preflight_docker() {
  # Cheap: does the binary even exist?
  if ! command -v docker &>/dev/null; then
    err "docker CLI not found in PATH — install docker first."
    return 127
  fi

  # Is the socket present at all?
  local sock=/var/run/docker.sock
  if [[ ! -S "$sock" ]]; then
    err "Docker socket $sock not present — is dockerd running?"
    err "Try: sudo systemctl status docker"
    return 1
  fi

  # Bounded probe: `docker info` normally returns in <1s on a healthy daemon.
  # If it takes more than 5s, dockerd is either starting, overloaded, or
  # wedged in D-state — either way we don't want to inherit the wait.
  if with_timeout 5 docker info &>/dev/null; then
    return 0
  fi

  # Daemon is unresponsive. Before giving up, print a focused diagnosis so
  # the user isn't left wondering why vox bailed.
  echo ""
  err "Docker daemon is not responding (timed out after 5s)."
  echo ""

  # Look for D-state dockerd — the classic overlay2-on-ZFS deadlock signature.
  local wedged=""
  wedged=$(ps -eo pid,stat,comm 2>/dev/null | awk '$3=="dockerd" && $2 ~ /D/ {print $1}' | head -5)
  if [[ -n "$wedged" ]]; then
    err "Found dockerd processes stuck in D-state (uninterruptible I/O wait):"
    while IFS= read -r p; do echo "        PID $p"; done <<< "$wedged"
    echo ""
    err "This usually means overlay2 cleanup deadlocked against ZFS."
    err "D-state processes cannot be killed — the only fix is a reboot."
    echo ""
    err "Permanent fix (do this after the reboot, before starting docker):"
    echo "        sudo tee /etc/docker/daemon.json > /dev/null <<'JSON'"
    echo "        {"
    echo "            \"data-root\": \"/data/docker\","
    echo "            \"storage-driver\": \"zfs\""
    echo "        }"
    echo "        JSON"
    echo "        sudo rm -rf /data/docker/overlay2   # discard old layers"
    echo "        sudo systemctl start docker"
  else
    err "Docker daemon exists but isn't responding. Possible causes:"
    err "  • Daemon still starting → wait ~30s and retry"
    err "  • Daemon crashed       → sudo systemctl status docker"
    err "  • Socket permissions   → check group membership for 'docker'"
  fi
  echo ""
  return 1
}

# Run preflight once per invocation; cache the result so multiple subcommands
# in a single vox call don't each pay the probe cost.
DOCKER_PREFLIGHT_DONE=""
require_docker() {
  [[ "$DOCKER_PREFLIGHT_DONE" == "yes" ]] && return 0
  if preflight_docker; then
    DOCKER_PREFLIGHT_DONE="yes"
    return 0
  fi
  exit 1
}

# Ensure we can run privileged commands non-interactively.
#   $1 = "interactive" → may prompt for the password once and cache it
#   $1 = "auto"        → never prompt; just probe and remember the answer
# Returns 0 if privileged commands will work, 1 otherwise.
ensure_sudo() {
  local mode="${1:-auto}"

  # Already cached.
  [[ "$SUDO_OK" == "yes" ]] && return 0
  [[ "$SUDO_OK" == "no"  ]] && return 1

  # Running as root → no sudo needed.
  if [[ "$(id -u)" == "0" ]]; then
    SUDO_OK="yes"
    return 0
  fi

  # No sudo binary at all → give up.
  if ! command -v sudo &>/dev/null; then
    SUDO_OK="no"
    warn "sudo not found — privileged steps will be skipped."
    return 1
  fi

  # Passwordless sudo already works (root, NOPASSWD, or fresh timestamp).
  if sudo -n true 2>/dev/null; then
    SUDO_OK="yes"
    return 0
  fi

  # Need a password. In auto mode we refuse to block.
  if [[ "$mode" != "interactive" ]]; then
    SUDO_OK="no"
    return 1
  fi

  # Interactive: prompt the user once and cache the credential.
  echo ""
  warn "Some setup steps need root privileges (apt-get, nvidia-ctk, systemctl)."
  info "You will be prompted for your sudo password once; it will be cached."
  if with_timeout 120 sudo -v; then
    SUDO_OK="yes"
    return 0
  else
    SUDO_OK="no"
    warn "sudo authentication failed or timed out — privileged steps will be skipped."
    return 1
  fi
}

# Run a privileged command with a hard timeout. Stderr is intentionally NOT
# suppressed so the user always sees real failures. Returns the command's
# exit code, or 126 if sudo is unavailable.
sudo_run() {
  local secs="$1"; shift
  if [[ "$(id -u)" == "0" ]]; then
    with_timeout "$secs" "$@"
    return $?
  fi
  if [[ "$SUDO_OK" != "yes" ]]; then
    return 126
  fi
  with_timeout "$secs" sudo -n "$@"
  return $?
}

ask() {
  local varname="$1" text="$2" default="${3:-}"
  if [[ -n "$default" ]]; then
    prompt "  $text [$default]: "
  else
    prompt "  $text: "
  fi
  read -r input
  eval "$varname=\"${input:-$default}\""
}

ask_secret() {
  local varname="$1" text="$2" default="${3:-}"
  if [[ -n "$default" ]]; then
    prompt "  $text [$default]: "
  else
    prompt "  $text: "
  fi
  read -rs input
  echo ""
  eval "$varname=\"${input:-$default}\""
}

confirm() {
  prompt "  $1 [Y/n] (auto-no in 3s): "
  if read -r -t 3 yn; then
    case "${yn,,}" in
      n|no|"") return 1 ;;
      *)       return 0 ;;
    esac
  else
    echo ""
    return 1
  fi
}

# ═════════════════════════════════════════════════════════════════════════════
# DYNAMIC BOX RENDERING — adapts to terminal width
# ═════════════════════════════════════════════════════════════════════════════

BOX_LINES=()

box_line() {
  BOX_LINES+=("$1")
}

box_render() {
  # Get terminal width, default 80
  local cols
  cols=$(tput cols 2>/dev/null || echo 80)
  # Box inner width = terminal - 4 (border + padding each side)
  local inner=$((cols - 4))
  [[ "$inner" -lt 20 ]] && inner=20

  # Top border
  local hbar=""
  for ((i=0; i<inner+2; i++)); do hbar="${hbar}─"; done
  echo -e "${CYAN}╭${hbar}╮${NC}"

  # Content lines — pad/truncate to fit
  for line in "${BOX_LINES[@]}"; do
    # Strip ANSI for length calculation
    local plain
    plain=$(echo -e "$line" | sed 's/\x1b\[[0-9;]*m//g')
    local len=${#plain}

    if [[ "$len" -le "$inner" ]]; then
      # Pad with spaces
      local pad=$((inner - len))
      local spaces=""
      for ((i=0; i<pad; i++)); do spaces="${spaces} "; done
      echo -e "${CYAN}│${NC} ${line}${spaces} ${CYAN}│${NC}"
    else
      # Truncate
      echo -e "${CYAN}│${NC} ${line:0:$inner} ${CYAN}│${NC}"
    fi
  done

  # Bottom border
  echo -e "${CYAN}╰${hbar}╯${NC}"

  # Reset
  BOX_LINES=()
}

# ═════════════════════════════════════════════════════════════════════════════
# PROJECT AUTO-DETECTION ENGINE
# ═════════════════════════════════════════════════════════════════════════════

detect_project() {
  local repo="$1"

  # Result variables (globals)
  DETECTED_TYPE="unknown"
  DETECTED_BASE_IMAGE=""
  DETECTED_SYSTEM_DEPS=""
  DETECTED_INSTALL_CMD=""
  DETECTED_BUILD_CMD=""
  DETECTED_START_CMD=""
  DETECTED_PORT="3000"
  DETECTED_HAS_DOCKERFILE="false"
  DETECTED_COPY_DEPS=""     # files to copy for dep install layer
  DETECTED_IGNORE_PATTERNS=""
  DETECTED_DATA_DIRS=""     # dirs that should be volumes
  DETECTED_NATIVE_MODULES="" # native node modules needing rebuild

  # ── Check for existing Docker config ──
  if [[ -f "$repo/Dockerfile" ]]; then
    DETECTED_HAS_DOCKERFILE="true"
    detect "Found existing Dockerfile"
  fi
  for cfile in docker-compose.yml docker-compose.yaml compose.yml compose.yaml; do
    if [[ -f "$repo/$cfile" ]]; then
      detect "Found existing $cfile (will generate a new one with tunnel)"
      break
    fi
  done

  # ── Node.js ──
  if [[ -f "$repo/package.json" ]]; then
    DETECTED_TYPE="node"
    DETECTED_BASE_IMAGE="node:22-slim"
    # If repo has Python files (transcription sidecar, ML, etc.), use Debian slim
    # Alpine's musl breaks numpy/scipy/whisper pip wheels
    if compgen -G "$repo/*.py" > /dev/null 2>&1 || [[ -f "$repo/requirements.txt" ]] || [[ -f "$repo/Pipfile" ]]; then
      DETECTED_BASE_IMAGE="node:22-slim"
      detect "Python files detected — using node:22-slim (glibc) instead of alpine (musl)"
    fi
    DETECTED_COPY_DEPS="package.json package-lock.json* yarn.lock* pnpm-lock.yaml*"
    DETECTED_IGNORE_PATTERNS="node_modules\n.next\n.nuxt\ndist\nbuild\n.env.local\n.git"

    # Read package.json for details
    local pkg="$repo/package.json"

    # Detect package manager
    local pkg_mgr="npm"
    if [[ -f "$repo/pnpm-lock.yaml" ]]; then
      pkg_mgr="pnpm"
      DETECTED_BASE_IMAGE="node:22-slim"
      DETECTED_SYSTEM_DEPS="RUN corepack enable && corepack prepare pnpm@latest --activate"
    elif [[ -f "$repo/yarn.lock" ]]; then
      pkg_mgr="yarn"
    fi

    # ── Parse package.json scripts with a single python3 call ──
    # Extracts: scripts object, dependencies, devDependencies, main
    local pkg_json_data
    pkg_json_data=$(python3 -c "
import json, sys
d = json.load(open('$pkg'))
scripts = d.get('scripts', {})
deps = {**d.get('dependencies', {}), **d.get('devDependencies', {})}
# Print script names one per line, prefixed
for k in scripts:
    print(f'script:{k}={scripts[k]}')
for k in deps:
    print(f'dep:{k}')
print(f'main:{d.get(\"main\", \"\")}')
" 2>/dev/null || true)

    # Helper: check if a script exists
    has_script() { echo "$pkg_json_data" | grep -q "^script:$1=" 2>/dev/null; }
    get_script() { echo "$pkg_json_data" | grep "^script:$1=" 2>/dev/null | head -1 | sed 's/^script:[^=]*=//'; }
    has_dep()    { echo "$pkg_json_data" | grep -q "^dep:$1$" 2>/dev/null; }

    # Detect install command — always --ignore-scripts for Docker layer caching
    # (postinstall scripts often reference source files not yet copied)
    if has_script "postinstall"; then
      detect "postinstall script found: $(get_script postinstall)"
      detect "Will use --ignore-scripts for Docker layer caching"
    fi

    # ── Lockfile-drift-tolerant install command ──
    # Strict-lockfile mode (`npm ci`, `pnpm --frozen-lockfile`, `yarn
    # --frozen-lockfile`) is the right default for reproducible images —
    # but it makes the whole deploy fail any time a dep version is bumped
    # in the manifest without re-running the host install to refresh the
    # lockfile. That has caused production retry loops here (omnius 1.0.199
    # in lock vs 1.0.200 in package.json triggered every-15s build failures
    # for an hour until manually fixed). Each command therefore falls back
    # to a permissive install on strict-mode failure, with a logged warning
    # so the drift is visible in build logs. The warning text "[vox]"
    # prefix and "lockfile likely drifted" phrase are grepped by ops, so
    # don't reword without updating dashboards.
    case "$pkg_mgr" in
      pnpm) DETECTED_INSTALL_CMD='pnpm install --frozen-lockfile --ignore-scripts || (echo "[vox] pnpm frozen-lockfile failed (lockfile likely drifted) — falling back to pnpm install" && pnpm install --ignore-scripts)' ;;
      yarn) DETECTED_INSTALL_CMD='yarn install --frozen-lockfile --ignore-scripts || (echo "[vox] yarn frozen-lockfile failed (lockfile likely drifted) — falling back to yarn install" && yarn install --ignore-scripts)' ;;
      *)    DETECTED_INSTALL_CMD='npm ci --ignore-scripts --legacy-peer-deps || (echo "[vox] npm ci failed (lockfile likely drifted) — falling back to npm install" && npm install --ignore-scripts --legacy-peer-deps --no-audit --no-fund)' ;;
    esac

    if echo "$DETECTED_BASE_IMAGE" | grep -q "slim\|debian\|ubuntu"; then
      DETECTED_SYSTEM_DEPS="${DETECTED_SYSTEM_DEPS:+$DETECTED_SYSTEM_DEPS\n}RUN apt-get update && apt-get install -y --no-install-recommends bash ca-certificates curl postgresql-client && rm -rf /var/lib/apt/lists/*"
      detect "Node runtime uses Debian slim — adding bash, curl, CA certs, and psql"
    elif echo "$DETECTED_BASE_IMAGE" | grep -q "alpine"; then
      DETECTED_SYSTEM_DEPS="${DETECTED_SYSTEM_DEPS:+$DETECTED_SYSTEM_DEPS\n}RUN apk add --no-cache bash ca-certificates curl postgresql-client"
      detect "Node runtime uses Alpine — adding bash, curl, CA certs, and psql"
    fi

    # Check for native modules that need build tools
    local has_native=0
    local native_modules=""
    for mod in argon2 better-sqlite3 bcrypt sharp canvas sqlite3 node-gyp; do
      if has_dep "$mod"; then
        has_native=1
        native_modules="${native_modules:+$native_modules }$mod"
      fi
    done
    if [[ "$has_native" -eq 1 ]]; then
      if echo "$DETECTED_BASE_IMAGE" | grep -q "alpine"; then
        DETECTED_SYSTEM_DEPS="${DETECTED_SYSTEM_DEPS:+$DETECTED_SYSTEM_DEPS\n}RUN apk add --no-cache python3 make g++ gcc musl-dev"
      else
        DETECTED_SYSTEM_DEPS="${DETECTED_SYSTEM_DEPS:+$DETECTED_SYSTEM_DEPS\n}RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv python3-pip make g++ gcc && rm -rf /var/lib/apt/lists/*"
      fi
      detect "Native modules detected ($native_modules) — adding build tools"
    fi
    # Store for Dockerfile generator
    DETECTED_NATIVE_MODULES="$native_modules"

    # Detect framework from dependencies
    local framework=""
    if has_dep "next";              then framework="next"
    elif has_dep "nuxt";            then framework="nuxt"
    elif has_dep "@remix-run/node";  then framework="remix"
    elif has_dep "@remix-run/react"; then framework="remix"
    elif has_dep "astro";           then framework="astro"
    elif has_dep "@sveltejs/kit";   then framework="sveltekit"
    elif has_dep "vite";            then framework="vite"
    elif has_dep "express";         then framework="express"
    elif has_dep "fastify";         then framework="fastify"
    elif has_dep "hono";            then framework="hono"
    elif has_dep "koa";             then framework="koa"
    fi

    # Read actual build/start scripts from package.json
    local pkg_build_script="" pkg_start_script=""
    has_script "build" && pkg_build_script="$(get_script build)"
    has_script "start" && pkg_start_script="$(get_script start)"

    # ── Detect dangerous lifecycle scripts ──
    # prebuild/prestart/predev often contain dev-machine ops (kill-port, etc.)
    # that break inside Docker (killing PID 1 = killing the build).
    # When found, we bypass npm run and call the underlying command directly.
    local has_dangerous_prebuild=0 has_dangerous_prestart=0
    local prebuild_script="" prestart_script=""

    if has_script "prebuild"; then
      prebuild_script="$(get_script prebuild)"
      # Flag if it contains kill, port-kill, fuser, lsof, or process management
      if echo "$prebuild_script" | grep -qiE 'kill|fuser|lsof|pkill|taskkill'; then
        has_dangerous_prebuild=1
        warn "prebuild contains process-killing ops — will bypass for Docker"
        detect "prebuild: $prebuild_script"
      fi
    fi
    if has_script "prestart"; then
      prestart_script="$(get_script prestart)"
      if echo "$prestart_script" | grep -qiE 'kill|fuser|lsof|pkill|taskkill'; then
        has_dangerous_prestart=1
        warn "prestart contains process-killing ops — will bypass for Docker"
        detect "prestart: $prestart_script"
      fi
    fi

    # ── Resolve build command ──
    # If prebuild is dangerous, run the raw build command directly (e.g. "next build")
    # instead of "npm run build" which triggers prebuild → death
    resolve_build_cmd() {
      if [[ "$has_dangerous_prebuild" -eq 1 ]] && [[ -n "$pkg_build_script" ]]; then
        if echo "$pkg_build_script" | grep -qE '^(node|python|ruby|php|java|go|./|/)'; then
          echo "$pkg_build_script"
        else
          echo "npx $pkg_build_script"
        fi
      elif [[ -n "$pkg_build_script" ]]; then
        echo "${pkg_mgr} run build"
      else
        echo ""
      fi
    }

    # ── Resolve start command ──
    # Same logic: if prestart is dangerous, use the raw command
    resolve_start_cmd() {
      if [[ "$has_dangerous_prestart" -eq 1 ]] && [[ -n "$pkg_start_script" ]]; then
        # Run raw command directly, bypassing prestart lifecycle
        # Don't prepend npx if already starts with node/python/etc
        if echo "$pkg_start_script" | grep -qE '^(node|python|ruby|php|java|go|./|/)'; then
          echo "$pkg_start_script"
        else
          echo "npx $pkg_start_script"
        fi
      elif [[ -n "$pkg_start_script" ]]; then
        echo "${pkg_mgr} start"
      else
        echo ""
      fi
    }

    # Set build/start per framework
    case "$framework" in
      next)
        DETECTED_TYPE="node/nextjs"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        DETECTED_START_CMD="$(resolve_start_cmd)"
        [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx next build"
        [[ -z "$DETECTED_START_CMD" ]] && DETECTED_START_CMD="npx next start"
        DETECTED_PORT="3000"
        detect "Next.js detected (build: $DETECTED_BUILD_CMD, start: $DETECTED_START_CMD)"
        ;;
      nuxt)
        DETECTED_TYPE="node/nuxt"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx nuxt build"
        DETECTED_START_CMD="node .output/server/index.mjs"
        DETECTED_PORT="3000"
        detect "Nuxt detected"
        ;;
      remix)
        DETECTED_TYPE="node/remix"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        DETECTED_START_CMD="$(resolve_start_cmd)"
        [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx remix build"
        [[ -z "$DETECTED_START_CMD" ]] && DETECTED_START_CMD="${pkg_mgr} start"
        DETECTED_PORT="3000"
        detect "Remix detected"
        ;;
      astro)
        DETECTED_TYPE="node/astro"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx astro build"
        DETECTED_START_CMD="node ./dist/server/entry.mjs"
        DETECTED_PORT="4321"
        detect "Astro detected"
        ;;
      sveltekit)
        DETECTED_TYPE="node/sveltekit"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx svelte-kit build"
        DETECTED_START_CMD="node build"
        DETECTED_PORT="3000"
        detect "SvelteKit detected"
        ;;
      vite)
        if [[ -z "$pkg_start_script" ]]; then
          DETECTED_TYPE="node/vite-static"
          DETECTED_BUILD_CMD="$(resolve_build_cmd)"
          [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx vite build"
          DETECTED_START_CMD="npx serve dist -l 3000"
          DETECTED_PORT="3000"
          detect "Vite SPA (static) — will serve with 'serve'"
        else
          DETECTED_TYPE="node/vite-ssr"
          DETECTED_BUILD_CMD="$(resolve_build_cmd)"
          DETECTED_START_CMD="$(resolve_start_cmd)"
          [[ -z "$DETECTED_BUILD_CMD" ]] && DETECTED_BUILD_CMD="npx vite build"
          [[ -z "$DETECTED_START_CMD" ]] && DETECTED_START_CMD="${pkg_mgr} start"
          DETECTED_PORT="3000"
          detect "Vite SSR detected (start: $DETECTED_START_CMD)"
        fi
        ;;
      express|fastify|hono|koa)
        DETECTED_TYPE="node/$framework"
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        DETECTED_START_CMD="$(resolve_start_cmd)"
        [[ -z "$DETECTED_START_CMD" ]] && DETECTED_START_CMD="${pkg_mgr} start"
        DETECTED_PORT="3000"
        detect "$framework server detected (start: $DETECTED_START_CMD)"
        ;;
      *)
        # Generic Node.js — read directly from scripts
        DETECTED_BUILD_CMD="$(resolve_build_cmd)"
        DETECTED_START_CMD="$(resolve_start_cmd)"

        if [[ -z "$DETECTED_START_CMD" ]]; then
          local main_entry
          main_entry=$(echo "$pkg_json_data" | grep "^main:" | sed 's/^main://')
          if [[ -n "$main_entry" ]]; then
            DETECTED_START_CMD="node $main_entry"
            detect "Generic Node.js (main: $main_entry)"
          else
            DETECTED_START_CMD="node index.js"
            detect "Generic Node.js (no start script, defaulting to index.js)"
          fi
        else
          detect "Generic Node.js (start: $DETECTED_START_CMD)"
        fi
        ;;
    esac

    # Show all discovered scripts to user
    local all_scripts
    all_scripts=$(echo "$pkg_json_data" | grep "^script:" | sed 's/^script:/  /' | head -20)
    if [[ -n "$all_scripts" ]]; then
      detect "package.json scripts:"
      echo "$all_scripts" | while IFS= read -r line; do
        echo -e "    ${MAGENTA}${line}${NC}"
      done
    fi

    # Look for data dirs that should be volumes
    if has_dep "better-sqlite3" || has_dep "sqlite3" || has_dep "nedb" || has_dep "lowdb"; then
      DETECTED_DATA_DIRS="data"
      detect "SQLite/file DB detected — will mount /app/data as volume"
    fi

    return 0
  fi

  # ── Python ──
  if [[ -f "$repo/requirements.txt" ]] || [[ -f "$repo/pyproject.toml" ]] || [[ -f "$repo/Pipfile" ]] || [[ -f "$repo/setup.py" ]]; then
    DETECTED_TYPE="python"
    DETECTED_BASE_IMAGE="python:3.12-slim"
    DETECTED_IGNORE_PATTERNS=".venv\nvenv\n__pycache__\n*.pyc\n.env.local\n.git\ndist\n*.egg-info"

    # Detect dependency file
    if [[ -f "$repo/pyproject.toml" ]]; then
      DETECTED_COPY_DEPS="pyproject.toml"
      if grep -q '\[tool.poetry\]' "$repo/pyproject.toml" 2>/dev/null; then
        DETECTED_INSTALL_CMD="pip install poetry && poetry install --no-root --no-interaction"
        DETECTED_COPY_DEPS="pyproject.toml poetry.lock*"
      elif grep -q '\[project\]' "$repo/pyproject.toml" 2>/dev/null; then
        DETECTED_INSTALL_CMD="pip install ."
        DETECTED_COPY_DEPS="pyproject.toml setup.cfg* setup.py*"
      else
        DETECTED_INSTALL_CMD="pip install ."
      fi
    elif [[ -f "$repo/Pipfile" ]]; then
      DETECTED_COPY_DEPS="Pipfile Pipfile.lock*"
      DETECTED_INSTALL_CMD="pip install pipenv && pipenv install --deploy --system"
    else
      DETECTED_COPY_DEPS="requirements.txt"
      DETECTED_INSTALL_CMD="pip install --no-cache-dir -r requirements.txt"
    fi

    # Detect framework
    local py_files
    py_files=$(cat "$repo/requirements.txt" "$repo/pyproject.toml" "$repo/Pipfile" 2>/dev/null || true)

    if echo "$py_files" | grep -qi "django"; then
      DETECTED_TYPE="python/django"
      DETECTED_BUILD_CMD="python manage.py collectstatic --noinput"
      DETECTED_START_CMD="gunicorn --bind 0.0.0.0:8000 --workers 4 config.wsgi:application"
      DETECTED_PORT="8000"
      # Try to find the wsgi module
      local wsgi_file
      wsgi_file=$(find "$repo" -name "wsgi.py" -not -path "*/venv/*" -not -path "*/.venv/*" 2>/dev/null | head -1)
      if [[ -n "$wsgi_file" ]]; then
        local wsgi_module
        wsgi_module=$(echo "$wsgi_file" | sed "s|$repo/||" | sed 's|/|.|g' | sed 's|\.py$||')
        DETECTED_START_CMD="gunicorn --bind 0.0.0.0:8000 --workers 4 ${wsgi_module}:application"
      fi
      DETECTED_SYSTEM_DEPS="RUN apt-get update && apt-get install -y --no-install-recommends gcc libpq-dev && rm -rf /var/lib/apt/lists/*"
      detect "Django project detected"

    elif echo "$py_files" | grep -qi "fastapi"; then
      DETECTED_TYPE="python/fastapi"
      DETECTED_BUILD_CMD=""
      # Find the main app module
      local app_entry="main:app"
      if [[ -f "$repo/app/main.py" ]]; then
        app_entry="app.main:app"
      elif [[ -f "$repo/src/main.py" ]]; then
        app_entry="src.main:app"
      fi
      DETECTED_START_CMD="uvicorn $app_entry --host 0.0.0.0 --port 8000"
      DETECTED_PORT="8000"
      detect "FastAPI project detected"

    elif echo "$py_files" | grep -qi "flask"; then
      DETECTED_TYPE="python/flask"
      DETECTED_BUILD_CMD=""
      local flask_app="app:app"
      if [[ -f "$repo/app.py" ]]; then
        flask_app="app:app"
      elif [[ -f "$repo/wsgi.py" ]]; then
        flask_app="wsgi:app"
      elif [[ -f "$repo/application.py" ]]; then
        flask_app="application:app"
      fi
      DETECTED_START_CMD="gunicorn --bind 0.0.0.0:5000 --workers 4 $flask_app"
      DETECTED_PORT="5000"
      detect "Flask project detected"

    elif echo "$py_files" | grep -qi "streamlit"; then
      DETECTED_TYPE="python/streamlit"
      DETECTED_BUILD_CMD=""
      local st_entry
      st_entry=$(find "$repo" -maxdepth 2 -name "*.py" \( -name "app.py" -o -name "main.py" -o -name "streamlit_app.py" \) 2>/dev/null | head -1)
      st_entry="${st_entry:-app.py}"
      st_entry="${st_entry#"$repo/"}"
      DETECTED_START_CMD="streamlit run $st_entry --server.port 8501 --server.address 0.0.0.0"
      DETECTED_PORT="8501"
      detect "Streamlit project detected"

    else
      # Generic Python
      DETECTED_BUILD_CMD=""
      if [[ -f "$repo/manage.py" ]]; then
        DETECTED_START_CMD="python manage.py runserver 0.0.0.0:8000"
        DETECTED_PORT="8000"
      elif [[ -f "$repo/app.py" ]]; then
        DETECTED_START_CMD="python app.py"
        DETECTED_PORT="8000"
      elif [[ -f "$repo/main.py" ]]; then
        DETECTED_START_CMD="python main.py"
        DETECTED_PORT="8000"
      else
        DETECTED_START_CMD="python -m http.server 8000"
        DETECTED_PORT="8000"
      fi
      detect "Generic Python project detected"
    fi

    return 0
  fi

  # ── Go ──
  if [[ -f "$repo/go.mod" ]]; then
    DETECTED_TYPE="go"
    DETECTED_BASE_IMAGE="golang:1.22-alpine"
    DETECTED_COPY_DEPS="go.mod go.sum*"
    DETECTED_INSTALL_CMD="go mod download"
    DETECTED_BUILD_CMD="CGO_ENABLED=0 go build -o /app/server ."
    DETECTED_START_CMD="/app/server"
    DETECTED_PORT="8080"
    DETECTED_IGNORE_PATTERNS=".git\n*.test\n.env.local"
    detect "Go project detected"
    return 0
  fi

  # ── Rust ──
  if [[ -f "$repo/Cargo.toml" ]]; then
    DETECTED_TYPE="rust"
    DETECTED_BASE_IMAGE="rust:1.77-slim"
    DETECTED_COPY_DEPS="Cargo.toml Cargo.lock*"
    DETECTED_INSTALL_CMD=""
    DETECTED_BUILD_CMD="cargo build --release"
    # Try to find binary name
    local bin_name
    bin_name=$(grep -m1 'name' "$repo/Cargo.toml" | sed 's/.*= *"\(.*\)"/\1/' || true)
    DETECTED_START_CMD="./target/release/${bin_name:-app}"
    DETECTED_PORT="8080"
    DETECTED_IGNORE_PATTERNS="target\n.git\n.env.local"
    detect "Rust project detected"
    return 0
  fi

  # ── Ruby ──
  if [[ -f "$repo/Gemfile" ]]; then
    DETECTED_TYPE="ruby"
    DETECTED_BASE_IMAGE="ruby:3.3-slim"
    DETECTED_COPY_DEPS="Gemfile Gemfile.lock*"
    DETECTED_INSTALL_CMD="bundle install"
    DETECTED_IGNORE_PATTERNS=".git\n.env.local\nvendor/bundle\ntmp\nlog"

    if [[ -f "$repo/config.ru" ]] || [[ -f "$repo/bin/rails" ]]; then
      DETECTED_TYPE="ruby/rails"
      DETECTED_BUILD_CMD="bundle exec rails assets:precompile"
      DETECTED_START_CMD="bundle exec rails server -b 0.0.0.0 -p 3000"
      DETECTED_PORT="3000"
      DETECTED_SYSTEM_DEPS="RUN apt-get update && apt-get install -y --no-install-recommends build-essential libpq-dev nodejs && rm -rf /var/lib/apt/lists/*"
      detect "Ruby on Rails project detected"
    else
      DETECTED_BUILD_CMD=""
      DETECTED_START_CMD="bundle exec ruby app.rb"
      DETECTED_PORT="4567"
      detect "Ruby (Sinatra/generic) project detected"
    fi
    return 0
  fi

  # ── PHP ──
  if [[ -f "$repo/composer.json" ]]; then
    DETECTED_TYPE="php"
    DETECTED_BASE_IMAGE="php:8.3-apache"
    DETECTED_COPY_DEPS="composer.json composer.lock*"
    DETECTED_INSTALL_CMD="composer install --no-dev --optimize-autoloader"
    DETECTED_IGNORE_PATTERNS="vendor\n.git\n.env.local\nstorage/logs"

    if [[ -f "$repo/artisan" ]]; then
      DETECTED_TYPE="php/laravel"
      DETECTED_BUILD_CMD="php artisan config:cache && php artisan route:cache && php artisan view:cache"
      DETECTED_START_CMD="php artisan serve --host=0.0.0.0 --port=8000"
      DETECTED_PORT="8000"
      DETECTED_DATA_DIRS="storage"
      detect "Laravel project detected"
    else
      DETECTED_BUILD_CMD=""
      DETECTED_START_CMD="apache2-foreground"
      DETECTED_PORT="80"
      detect "PHP project detected"
    fi
    return 0
  fi

  # ── Static site ──
  if [[ -f "$repo/index.html" ]]; then
    DETECTED_TYPE="static"
    DETECTED_BASE_IMAGE="nginx:alpine"
    DETECTED_COPY_DEPS=""
    DETECTED_INSTALL_CMD=""
    DETECTED_BUILD_CMD=""
    DETECTED_START_CMD=""  # nginx runs by default
    DETECTED_PORT="80"
    DETECTED_IGNORE_PATTERNS=".git\n.env.local"
    detect "Static site detected — will serve with nginx"
    return 0
  fi

  # ── Nothing matched ──
  warn "Could not auto-detect project type."
  return 1
}

# ═════════════════════════════════════════════════════════════════════════════
# ENV VAR DISCOVERY
# ═════════════════════════════════════════════════════════════════════════════

discover_env_vars() {
  local repo="$1"
  ENV_VARS=()        # array of KEY=VALUE
  ENV_VAR_KEYS=()    # just the keys
  # ── Option A: User provided a .env file (drag-and-drop / CLI arg) ──
  if [[ -n "$IMPORTED_ENV_FILE" ]]; then
    info "Importing env file: $IMPORTED_ENV_FILE"

    # Count vars
    local var_count
    var_count=$(grep -cE '^[A-Za-z_][A-Za-z0-9_]*=' "$IMPORTED_ENV_FILE" 2>/dev/null || echo 0)
    info "Found $var_count environment variables"

    # Parse into ENV_VARS array (for display / merge)
    while IFS= read -r line; do
      [[ "$line" =~ ^[[:space:]]*# ]] && continue
      [[ -z "${line// /}" ]] && continue
      if [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)= ]]; then
        local key="${BASH_REMATCH[1]}"
        ENV_VARS+=("$line")
        ENV_VAR_KEYS+=("$key")
      fi
    done < "$IMPORTED_ENV_FILE"

    # Show summary (mask secret values)
    echo ""
    for key in "${ENV_VAR_KEYS[@]}"; do
      if [[ "$key" =~ (SECRET|TOKEN|PASSWORD|KEY|PRIVATE|AUTH) ]]; then
        echo -e "    ${key}=${DIM}****${NC}"
      else
        local val
        val=$(grep "^${key}=" "$IMPORTED_ENV_FILE" | head -1 | sed "s/^${key}=//" || true)
        echo -e "    ${key}=${val:0:60}"
      fi
    done
    echo ""

    if [[ "$AUTO_MODE" != "true" ]] && confirm "Edit any of these values?"; then
      ENV_VARS=()
      while IFS= read -r line; do
        [[ "$line" =~ ^[[:space:]]*# ]] && continue
        [[ -z "${line// /}" ]] && continue
        if [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*) ]]; then
          local key="${BASH_REMATCH[1]}"
          local default_val="${BASH_REMATCH[2]}"
          default_val="${default_val#\"}"
          default_val="${default_val%\"}"
          default_val="${default_val#\'}"
          default_val="${default_val%\'}"
          local value
          if [[ "$key" =~ (SECRET|TOKEN|PASSWORD|KEY|PRIVATE|AUTH) ]]; then
            ask_secret value "$key" "$default_val"
          else
            ask value "$key" "$default_val"
          fi
          ENV_VARS+=("${key}=${value}")
        fi
      done < "$IMPORTED_ENV_FILE"
    fi
    return 0
  fi

  # ── Option B: No import — check for env example in repo, or ask manually ──

  # In auto mode, skip all interactive env prompts
  if [[ "$AUTO_MODE" == "true" ]]; then
    info "No .env file provided via --env. Continuing without app env vars."
    return 0
  fi

  # Also prompt: drag/drop an env file now
  echo ""
  box_line "Drag & drop a .env file here, paste a path, or press Enter to skip."
  box_render
  ask dropped_env_path "Path to .env file (or blank)" ""
  # Clean up drag-and-drop artifacts (quotes, whitespace)
  dropped_env_path=$(echo "$dropped_env_path" | sed "s/^['\"]//;s/['\"]$//;s/^[[:space:]]*//;s/[[:space:]]*$//")

  if [[ -n "$dropped_env_path" ]] && [[ -f "$dropped_env_path" ]]; then
    IMPORTED_ENV_FILE="$dropped_env_path"
    discover_env_vars "$repo"
    return 0
  fi

  # Look for env example files in repo
  local env_example=""
  for candidate in .env.example .env.sample .env.template .env.defaults .env.development; do
    if [[ -f "$repo/$candidate" ]]; then
      env_example="$repo/$candidate"
      detect "Found env template: $candidate"
      break
    fi
  done

  if [[ -n "$env_example" ]]; then
    echo ""
    info "Collecting environment variables from $(basename "$env_example")"
    info "Press Enter to keep default, or type a new value."
    echo ""

    while IFS= read -r line; do
      [[ "$line" =~ ^[[:space:]]*# ]] && continue
      [[ -z "${line// /}" ]] && continue

      if [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*) ]]; then
        local key="${BASH_REMATCH[1]}"
        local default_val="${BASH_REMATCH[2]}"
        default_val="${default_val#\"}"
        default_val="${default_val%\"}"
        default_val="${default_val#\'}"
        default_val="${default_val%\'}"

        local is_secret=0
        if [[ "$key" =~ (SECRET|TOKEN|PASSWORD|KEY|PRIVATE|AUTH) ]]; then
          is_secret=1
        fi

        local value
        if [[ "$is_secret" -eq 1 ]]; then
          ask_secret value "$key" "$default_val"
        else
          ask value "$key" "$default_val"
        fi
        ENV_VARS+=("${key}=${value}")
        ENV_VAR_KEYS+=("$key")
      fi
    done < "$env_example"
  else
    info "No .env.example found in repo."
  fi

  # Always offer to add custom vars
  echo ""
  if confirm "Add custom environment variables?"; then
    while true; do
      ask custom_key "Variable name (blank to finish)" ""
      [[ -z "$custom_key" ]] && break
      ask custom_val "$custom_key value" ""
      ENV_VARS+=("${custom_key}=${custom_val}")
      ENV_VAR_KEYS+=("$custom_key")
    done
  fi
}

# ═════════════════════════════════════════════════════════════════════════════
# DOCKERFILE GENERATOR
# ═════════════════════════════════════════════════════════════════════════════

generate_entrypoint() {
  local outfile="$1" start_cmd="$2" port="$3"
  cat > "$outfile" <<'ENTRYEOF'
#!/bin/sh
set -e

# ── vox entrypoint: cloudflared + app in one container ──

cleanup() {
  echo "[vox] shutting down..."
  kill "$CF_PID" "$APP_PID" 2>/dev/null || true
  wait "$CF_PID" "$APP_PID" 2>/dev/null || true
  exit 0
}
trap cleanup TERM INT

# ── Ensure app binds to 0.0.0.0 (reachable by tunnel within container) ──
export HOSTNAME="${HOSTNAME_OVERRIDE:-0.0.0.0}"
export HOST="${HOST:-0.0.0.0}"
export PORT="${PORT:-__VOX_PORT__}"

# ── Start cloudflared tunnel inside the container ──
if [ -n "${TUNNEL_TOKEN:-}" ]; then
  echo "[vox] starting cloudflared tunnel (token mode)..."
  cloudflared tunnel run --token "$TUNNEL_TOKEN" &
  CF_PID=$!
elif [ -f /etc/cloudflared/credentials.json ]; then
  echo "[vox] starting cloudflared tunnel (credentials mode)..."
  cloudflared tunnel --config /etc/cloudflared/config.yml run &
  CF_PID=$!
else
  echo "[vox] WARNING: no TUNNEL_TOKEN or credentials found — tunnel disabled"
  CF_PID=""
fi

# ── Start the application ──
ENTRYEOF

  # Write the app start command
  sed -i "s/__VOX_PORT__/${port}/g" "$outfile"
  cat >> "$outfile" <<STARTEOF
echo "[vox] starting app on port ${port}..."
${start_cmd} &
APP_PID=\$!

echo "[vox] running — app=\$APP_PID tunnel=\${CF_PID:-none}"
wait -n 2>/dev/null || wait \$APP_PID
STARTEOF

  chmod +x "$outfile"
}

generate_dockerfile() {
  local repo="$1" outfile="$2"

  # ── All Dockerfiles include cloudflared inside the image ──
  # This means every container is fully self-contained: app + tunnel.

  # Static sites — nginx + cloudflared
  if [[ "$DETECTED_TYPE" == "static" ]]; then
    cat > "$outfile" <<'STATICEOF'
FROM nginx:alpine
RUN apk add --no-cache curl && \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared
COPY . /usr/share/nginx/html
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
STATICEOF
    generate_entrypoint "$repo/entrypoint.sh" "nginx -g 'daemon off;'" "$DETECTED_PORT"
    return 0
  fi

  # Go — multi-stage build + cloudflared in final stage
  if [[ "$DETECTED_TYPE" == "go" ]]; then
    cat > "$outfile" <<GOEOF
FROM golang:1.22-alpine AS builder
WORKDIR /src
COPY go.mod go.sum* ./
RUN go mod download
COPY . .
RUN ${DETECTED_BUILD_CMD}

FROM alpine:3.19
RUN apk add --no-cache ca-certificates curl && \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared
WORKDIR /app
COPY --from=builder /app/server .
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
GOEOF
    generate_entrypoint "$repo/entrypoint.sh" "${DETECTED_START_CMD}" "$DETECTED_PORT"
    return 0
  fi

  # Rust — multi-stage build + cloudflared in final stage
  if [[ "$DETECTED_TYPE" == "rust" ]]; then
    cat > "$outfile" <<RUSTEOF
FROM rust:1.77-slim AS builder
WORKDIR /src
COPY Cargo.toml Cargo.lock* ./
RUN mkdir src && echo "fn main() {}" > src/main.rs && cargo build --release && rm -rf src
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl && \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared && \
    rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=builder /src/target/release/* ./
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
RUSTEOF
    generate_entrypoint "$repo/entrypoint.sh" "${DETECTED_START_CMD}" "$DETECTED_PORT"
    return 0
  fi

  # ── Generic Dockerfile (Node, Python, Ruby, PHP, etc.) ──
  local is_node=0
  if [[ "$DETECTED_TYPE" == node/* ]] || [[ "$DETECTED_TYPE" == "node" ]]; then
    is_node=1
  fi

  # Determine how to install cloudflared based on base image
  local cf_install=""
  if echo "$DETECTED_BASE_IMAGE" | grep -q "alpine"; then
    cf_install='RUN apk add --no-cache curl && \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared'
  elif echo "$DETECTED_BASE_IMAGE" | grep -q "slim\|debian\|ubuntu"; then
    cf_install='RUN apt-get update && apt-get install -y --no-install-recommends curl && \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared && \
    rm -rf /var/lib/apt/lists/*'
  else
    # Fallback: download static binary (works on any Linux)
    cf_install='RUN curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared'
  fi

  {
    echo "FROM ${DETECTED_BASE_IMAGE}"
    echo ""

    # System deps
    if [[ -n "$DETECTED_SYSTEM_DEPS" ]]; then
      echo -e "$DETECTED_SYSTEM_DEPS"
      echo ""
    fi

    # Install cloudflared inside the image
    echo "# Cloudflare tunnel daemon — runs inside the container"
    echo "$cf_install"
    echo ""

    echo "WORKDIR /app"
    echo ""

    # ── Dependency layer (cached) ──
    if [[ -n "$DETECTED_COPY_DEPS" ]]; then
      echo "# Dependencies (cached layer — install before source copy)"
      for dep_file in $DETECTED_COPY_DEPS; do
        echo "COPY ${dep_file} ./"
      done
      echo "RUN ${DETECTED_INSTALL_CMD}"
      echo ""
    fi

    # ── Source copy ──
    echo "# Application source"
    echo "COPY . ."
    echo ""

    # ── Post-copy: rebuild native modules ──
    if [[ "$is_node" -eq 1 ]] && [[ -n "${DETECTED_NATIVE_MODULES:-}" ]]; then
      echo "# Rebuild native modules against source tree"
      echo "RUN npm rebuild ${DETECTED_NATIVE_MODULES}"
      echo ""
    fi

    # ── Python sidecar (transcription, ML, etc.) ──
    if compgen -G "$repo/*.py" > /dev/null 2>&1; then
      echo "# Python sidecar dependencies"
      echo "RUN python3 -m venv /app/.venv && \\"
      echo "    /app/.venv/bin/pip install --no-cache-dir numpy 2>/dev/null && \\"
      echo "    /app/.venv/bin/pip install --no-cache-dir faster-whisper 2>/dev/null || \\"
      echo "    /app/.venv/bin/pip install --no-cache-dir openai-whisper 2>/dev/null || \\"
      echo '    echo "[vox] No whisper backend installed — transcription unavailable"'
      echo ""
    fi

    # ── Build step ──
    # Frameworks like Next.js need env vars during build for SSR/pre-render.
    # Source .env if present, run build, then delete .env from image.
    # Runtime env comes from docker env_file, not baked into the image.
    if [[ -n "$DETECTED_BUILD_CMD" ]]; then
      echo "RUN if [ -f .env ]; then set -a && . ./.env && set +a; fi && ${DETECTED_BUILD_CMD}"
      echo "RUN rm -f .env"
      echo ""
    fi

    # Data volume
    if [[ -n "$DETECTED_DATA_DIRS" ]]; then
      for ddir in $DETECTED_DATA_DIRS; do
        echo "VOLUME [\"/app/$ddir\"]"
      done
      echo ""
    fi

    # Entrypoint — manages both cloudflared + app
    echo "COPY entrypoint.sh /entrypoint.sh"
    echo "RUN chmod +x /entrypoint.sh"
    echo "ENTRYPOINT [\"/entrypoint.sh\"]"
  } > "$outfile"

  # Generate the entrypoint script
  generate_entrypoint "$repo/entrypoint.sh" "${DETECTED_START_CMD}" "$DETECTED_PORT"
}

# ═════════════════════════════════════════════════════════════════════════════
# DOCKER-COMPOSE GENERATOR
# ═════════════════════════════════════════════════════════════════════════════

env_var_value() {
  local key="$1" entry
  for entry in "${ENV_VARS[@]+"${ENV_VARS[@]}"}"; do
    if [[ "$entry" == "$key="* ]]; then
      printf '%s\n' "${entry#*=}"
      return 0
    fi
  done
  return 1
}

env_var_has_usable_value() {
  local value
  value="$(env_var_value "$1" 2>/dev/null || true)"
  [[ -n "$value" ]] && ! echo "$value" | grep -qiE '^replace-with|changeme|change-me|your-|todo|example'
}

env_vars_upsert() {
  local key="$1" value="$2" idx updated=0
  for idx in "${!ENV_VARS[@]}"; do
    if [[ "${ENV_VARS[$idx]}" == "$key="* ]]; then
      ENV_VARS[$idx]="$key=$value"
      updated=1
    fi
  done
  if [[ "$updated" -eq 0 ]]; then
    ENV_VARS+=("$key=$value")
  fi
}

ensure_generated_secret() {
  local key="$1" bytes="${2:-32}"
  if ! env_var_has_usable_value "$key"; then
    env_vars_upsert "$key" "$(random_hex "$bytes")"
    detect "Generated stable $key for container runtime"
  fi
}

random_hex() {
  local bytes="${1:-32}"
  if command -v openssl >/dev/null 2>&1; then
    openssl rand -hex "$bytes"
  else
    LC_ALL=C tr -dc 'a-f0-9' </dev/urandom | head -c $((bytes * 2))
    echo ""
  fi
}

yaml_quote() {
  local value="$1"
  value="${value//\\/\\\\}"
  value="${value//\"/\\\"}"
  printf '"%s"' "$value"
}

docker_host_url() {
  local value="$1"
  value="${value//127.0.0.1/host.docker.internal}"
  value="${value//localhost/host.docker.internal}"
  printf '%s\n' "$value"
}

is_loopback_url() {
  local value="$1"
  [[ "$value" == *"127.0.0.1"* || "$value" == *"localhost"* ]]
}

port_is_listening() {
  local port="$1"
  if command -v ss >/dev/null 2>&1; then
    ss -ltn "( sport = :$port )" 2>/dev/null | grep -q LISTEN
  elif command -v lsof >/dev/null 2>&1; then
    lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1
  else
    return 1
  fi
}

choose_host_port() {
  local port="$1"
  while port_is_listening "$port"; do
    port=$((port + 1))
  done
  printf '%s\n' "$port"
}

generate_compose() {
  local outfile="$1" repo_dir="$2"
  local container_name
  container_name=$(echo "$repo_dir" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-*$//')

  # ── App + cloudflared tunnel, with optional managed backing services ──
  local needs_postgres=0 needs_redis=0 skip_local_services=0 use_host_network=0 needs_host_gateway=0
  local repo_path="$WORK_DIR/$repo_dir"
  local pkg="$repo_path/package.json"

  if env_var_value "DATABASE_URL" >/dev/null 2>&1 || env_var_value "PGHOST" >/dev/null 2>&1; then
    needs_postgres=1
  elif [[ -f "$pkg" ]] && grep -qE '"(db:migrate|db:apply|db:ensure|db:push)"|drizzle|@neondatabase/serverless|"pg"' "$pkg"; then
    needs_postgres=1
  fi

  if env_var_value "REDIS_URL" >/dev/null 2>&1 || env_var_value "MCP_SESSION_REDIS_URL" >/dev/null 2>&1; then
    needs_redis=1
  elif [[ -f "$pkg" ]] && grep -qE '"redis"|"rate-limit-redis"' "$pkg"; then
    needs_redis=1
  fi

  if [[ -f "$repo_path/scripts/ensure-services.sh" ]] || { [[ -f "$pkg" ]] && grep -q "services:ensure" "$pkg"; }; then
    skip_local_services=1
  fi

  local host_url_key host_url_value
  for host_url_key in OMNIUS_BASE_URL OA_BASE_URL LLM_BASE_URL; do
    host_url_value="$(env_var_value "$host_url_key" 2>/dev/null || true)"
    if [[ -n "$host_url_value" ]] && is_loopback_url "$host_url_value"; then
      use_host_network=1
    fi
  done

  local app_port="$DETECTED_PORT"
  local pg_host_port="15432"
  local redis_host_port="16379"
  if [[ "$use_host_network" -eq 1 ]]; then
    app_port="$(choose_host_port "$app_port")"
    pg_host_port="$(choose_host_port "$pg_host_port")"
    redis_host_port="$(choose_host_port "$redis_host_port")"
    if [[ "$app_port" != "$DETECTED_PORT" ]]; then
      warn "Port $DETECTED_PORT is already in use; using $app_port for the host-network app container"
    fi
    if [[ "$needs_postgres" -eq 1 && "$pg_host_port" != "15432" ]]; then
      warn "Postgres helper port 15432 is already in use; using $pg_host_port"
    fi
    if [[ "$needs_redis" -eq 1 && "$redis_host_port" != "16379" ]]; then
      warn "Redis helper port 16379 is already in use; using $redis_host_port"
    fi
  fi

  local auth_secret signing_kek session_secret
  auth_secret="$(env_var_value "AUTH_JWT_SECRET" 2>/dev/null || true)"
  signing_kek="$(env_var_value "SIGNING_KEK_HEX" 2>/dev/null || true)"
  session_secret="$(env_var_value "SESSION_SECRET" 2>/dev/null || true)"
  env_var_has_usable_value "AUTH_JWT_SECRET" || auth_secret="$(random_hex 32)"
  env_var_has_usable_value "SIGNING_KEK_HEX" || signing_kek="$(random_hex 32)"
  env_var_has_usable_value "SESSION_SECRET" || session_secret="$(random_hex 32)"

  local volume_block=""
  local volume_def=""
  if [[ -n "$DETECTED_DATA_DIRS" ]]; then
    for ddir in $DETECTED_DATA_DIRS; do
      local vol_name="${container_name}-${ddir}"
      volume_block="${volume_block}      - ${vol_name}:/app/${ddir}\n"
      volume_def="${volume_def}  ${vol_name}:\n"
    done
  fi
  if [[ "$needs_postgres" -eq 1 ]]; then
    volume_def="${volume_def}  ${container_name}-pgdata:\n"
  fi
  if [[ "$needs_redis" -eq 1 ]]; then
    volume_def="${volume_def}  ${container_name}-redisdata:\n"
  fi

  local hc_cmd
  hc_cmd="[\"CMD\", \"sh\", \"-c\", \"curl -sf http://localhost:${app_port}/ > /dev/null || wget -qO- http://localhost:${app_port}/ > /dev/null || exit 1\"]"

  {
    cat <<COMPHEAD
# Generated by vox — $(date -Iseconds)
# Single container: app + cloudflared tunnel (fully isolated from host)

services:
COMPHEAD

    if [[ "$needs_postgres" -eq 1 ]]; then
      cat <<PGSVC
  postgres:
    image: postgres:16-alpine
    container_name: ${container_name}-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: app_password
      POSTGRES_DB: app_db
    volumes:
      - ${container_name}-pgdata:/var/lib/postgresql/data
PGSVC
      if [[ "$use_host_network" -eq 1 ]]; then
        echo "    ports:"
        echo "      - \"127.0.0.1:${pg_host_port}:5432\""
      fi
      cat <<PGSVC
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app_user -d app_db"]
      interval: 10s
      timeout: 5s
      retries: 10

PGSVC
    fi

    if [[ "$needs_redis" -eq 1 ]]; then
      cat <<REDISSVC
  redis:
    image: redis:7-alpine
    container_name: ${container_name}-redis
    restart: unless-stopped
    volumes:
      - ${container_name}-redisdata:/data
REDISSVC
      if [[ "$use_host_network" -eq 1 ]]; then
        echo "    ports:"
        echo "      - \"127.0.0.1:${redis_host_port}:6379\""
      fi
      cat <<REDISSVC
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 10

REDISSVC
    fi

    cat <<COMPHEAD
  ${container_name}:
    build:
      context: ./${repo_dir}
      dockerfile: Dockerfile
    container_name: ${container_name}
    restart: unless-stopped
    env_file: ./${repo_dir}/.env
COMPHEAD

    if [[ "$use_host_network" -eq 1 ]]; then
      echo "    network_mode: host"
    fi

    # cloudflared fails against some host stub resolvers from host-networked containers.
    echo "    dns:"
    echo "      - 1.1.1.1"
    echo "      - 1.0.0.1"

    echo "    environment:"
    echo "      PORT: \"${app_port}\""
    local runtime_key runtime_value runtime_out
    for runtime_key in \
      OMNIUS_BASE_URL OA_BASE_URL LLM_BASE_URL \
      OMNIUS_CHAT_MODEL OA_CHAT_MODEL LLM_MODEL \
      OMNIUS_TOOL_MODEL OA_TOOL_MODEL \
      OMNIUS_EMBED_MODEL OA_EMBED_MODEL
    do
      runtime_value="$(env_var_value "$runtime_key" 2>/dev/null || true)"
      [[ -z "$runtime_value" ]] && continue
      runtime_out="$runtime_value"
      if [[ "$use_host_network" -eq 0 && "$runtime_key" == *"_BASE_URL" ]] && is_loopback_url "$runtime_value"; then
        runtime_out="$(docker_host_url "$runtime_value")"
        needs_host_gateway=1
      fi
      echo "      ${runtime_key}: $(yaml_quote "$runtime_out")"
    done
    if [[ "$needs_postgres" -eq 1 ]]; then
      if [[ "$use_host_network" -eq 1 ]]; then
        cat <<APPDBENV
      DATABASE_URL: postgresql://app_user:app_password@127.0.0.1:${pg_host_port}/app_db
      PGHOST: 127.0.0.1
      PGPORT: "${pg_host_port}"
      PGDATABASE: app_db
      PGUSER: app_user
      PGPASSWORD: app_password
APPDBENV
      else
        cat <<APPDBENV
      DATABASE_URL: postgresql://app_user:app_password@postgres:5432/app_db
      PGHOST: postgres
      PGPORT: "5432"
      PGDATABASE: app_db
      PGUSER: app_user
      PGPASSWORD: app_password
APPDBENV
      fi
    fi
    if [[ "$needs_redis" -eq 1 ]]; then
      if [[ "$use_host_network" -eq 1 ]]; then
        echo "      REDIS_URL: redis://127.0.0.1:${redis_host_port}"
      else
        echo "      REDIS_URL: redis://redis:6379"
      fi
    fi
    if [[ "$skip_local_services" -eq 1 ]]; then
      echo "      SKIP_LOCAL_SERVICES: \"1\""
    fi
    if [[ -n "$auth_secret" ]]; then
      echo "      AUTH_JWT_SECRET: $auth_secret"
    fi
    if [[ -n "$signing_kek" ]]; then
      echo "      SIGNING_KEK_HEX: $signing_kek"
    fi
    if [[ -n "$session_secret" ]]; then
      echo "      SESSION_SECRET: $session_secret"
    fi

    if [[ "$needs_host_gateway" -eq 1 ]]; then
      echo "    extra_hosts:"
      echo "      - \"host.docker.internal:host-gateway\""
    fi

    if [[ "$needs_postgres" -eq 1 || "$needs_redis" -eq 1 ]]; then
      echo "    depends_on:"
      if [[ "$needs_postgres" -eq 1 ]]; then
        echo "      postgres:"
        echo "        condition: service_healthy"
      fi
      if [[ "$needs_redis" -eq 1 ]]; then
        echo "      redis:"
        echo "        condition: service_healthy"
      fi
    fi

    # Volumes
    if [[ -n "$volume_block" ]]; then
      echo "    volumes:"
      echo -e "$volume_block" | sed '/^$/d'
    fi

    # Credentials file mount (only for non-token auth)
    if [[ -z "$CF_TUNNEL_TOKEN" ]] && [[ -n "${CF_CREDENTIALS_FILE:-}" ]]; then
      if [[ -z "$volume_block" ]]; then
        echo "    volumes:"
      fi
      echo "      - ./.cloudflared:/etc/cloudflared:ro"
    fi

    cat <<COMPHC
    healthcheck:
      test: ${hc_cmd}
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 90s
    # GPU passthrough — all available GPUs exposed to container
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    runtime: nvidia
COMPHC

    # Volume definitions
    if [[ -n "$volume_def" ]]; then
      echo ""
      echo "volumes:"
      echo -e "$volume_def" | sed '/^$/d'
    fi
  } > "$outfile"

  mkdir -p "$VOX_DIR" 2>/dev/null || true
  {
    echo "app=${app_port}"
    [[ "$needs_postgres" -eq 1 && "$use_host_network" -eq 1 ]] && echo "postgres=${pg_host_port}"
    [[ "$needs_redis" -eq 1 && "$use_host_network" -eq 1 ]] && echo "redis=${redis_host_port}"
  } > "$VOX_DIR/ports"
}

# ═════════════════════════════════════════════════════════════════════════════
# STATE DIRECTORY & CONFIG
# ═════════════════════════════════════════════════════════════════════════════

VOX_DIR=".vox"
VOX_CONFIG="$VOX_DIR/config.json"
VOX_DEPLOYS="$VOX_DIR/deploys"

vox_config_repo_dir() {
  local config_path="$1"
  python3 - "$config_path" <<'PYEOF' 2>/dev/null || true
import json
import sys

try:
    with open(sys.argv[1]) as f:
        print(json.load(f).get("repo_dir", ""))
except Exception:
    print("")
PYEOF
}

# The tracked vox script lives inside some repos, while the deploy state lives
# beside the repo. Resolve that parent deploy root before loading config.
vox_enter_work_dir() {
  local cwd parent repo_dir
  cwd="$(pwd)"

  if [[ -f "$cwd/$VOX_CONFIG" ]]; then
    return 0
  fi

  parent="$(cd "$cwd/.." && pwd)"
  if [[ -f "$parent/$VOX_CONFIG" ]]; then
    repo_dir=$(vox_config_repo_dir "$parent/$VOX_CONFIG")
    if [[ -n "$repo_dir" ]] && [[ "$parent/$repo_dir" -ef "$cwd" ]]; then
      cd "$parent"
      return 0
    fi
  fi

  return 0
}

vox_init_dirs() {
  mkdir -p "$VOX_DIR" "$VOX_DEPLOYS"
}

# Save config to .vox/config.json using python3
vox_save_config() {
  vox_init_dirs
  python3 - <<PYEOF
import json, os

cfg = {
    "project_name":          "$1",
    "repo_url":              "$2",
    "repo_branch":           "$3",
    "repo_dir":              "$4",
    "hostname":              "$5",
    "port":                  "$6",
    "type":                  "$7",
    "base_image":            "$8",
    "install_cmd":           "$9",
    "auto_install":          "${17}",
    "build_cmd":             "${10}",
    "start_cmd":             "${11}",
    "data_dirs":             "${12}",
    "tunnel_method":         "${13}",
    "use_existing_dockerfile": "${14}",
    "created_at":            "${15}",
    "compose_cmd":           "${16}",
}

with open("$VOX_CONFIG", "w") as f:
    json.dump(cfg, f, indent=2)
print("Config saved to $VOX_CONFIG")
PYEOF
}

# Load a single key from config.json using python3
vox_config_get() {
  local key="$1"
  python3 -c "
import json, sys
try:
    d = json.load(open('$VOX_CONFIG'))
    print(d.get('$key', ''))
except Exception:
    print('')
" 2>/dev/null || true
}

# Load all config keys into shell variables
vox_load_config() {
  vox_enter_work_dir

  if [[ ! -f "$VOX_CONFIG" ]]; then
    err "No config found at $VOX_CONFIG. Run './vox setup' first."
    exit 1
  fi

  CFG_PROJECT_NAME=$(vox_config_get "project_name")
  CFG_REPO_BRANCH=$(vox_config_get "repo_branch")
  CFG_REPO_DIR=$(vox_config_get "repo_dir")
  CFG_HOSTNAME=$(vox_config_get "hostname")
  CFG_TYPE=$(vox_config_get "type")
  CFG_COMPOSE_CMD=$(vox_config_get "compose_cmd")
  CFG_INSTALL_CMD=$(vox_config_get "install_cmd")
  CFG_AUTO_INSTALL=$(vox_config_get "auto_install")

  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  COMPOSE_CMD="${CFG_COMPOSE_CMD:-docker compose}"
}

vox_maybe_load_config() {
  vox_enter_work_dir

  if [[ -f "$VOX_CONFIG" ]]; then
    vox_load_config
    return 0
  fi

  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR"
  CFG_PROJECT_NAME=""
  CFG_REPO_BRANCH=""
  CFG_REPO_DIR=""
  CFG_HOSTNAME=""
  CFG_TYPE=""
  CFG_COMPOSE_CMD="docker compose"
  CFG_INSTALL_CMD=""
  CFG_AUTO_INSTALL=""
  COMPOSE_CMD="$CFG_COMPOSE_CMD"
  return 1
}

# Detect compose command (used during setup before config exists)
detect_compose_cmd() {
  if docker compose version &>/dev/null 2>&1; then
    echo "docker compose"
  elif command -v docker-compose &>/dev/null; then
    echo "docker-compose"
  else
    echo "docker compose"
  fi
}

# Log a deploy entry to .vox/deploys/<timestamp>.json
vox_log_deploy() {
  local status="$1"
  local ts
  ts=$(date -Iseconds)
  local safe_ts
  safe_ts=$(echo "$ts" | tr ':' '-')
  local git_sha=""
  if [[ -d "$REPO_PATH/.git" ]]; then
    git_sha=$(git -C "$REPO_PATH" rev-parse --short HEAD 2>/dev/null || true)
  fi
  local image_tag="${2:-}"

  vox_init_dirs
  python3 - <<PYEOF
import json
entry = {
    "timestamp":  "$ts",
    "git_sha":    "$git_sha",
    "image_tag":  "$image_tag",
    "status":     "$status",
}
with open("$VOX_DEPLOYS/${safe_ts}.json", "w") as f:
    json.dump(entry, f, indent=2)
PYEOF
}

# Wait for container healthcheck to pass (up to N seconds)
wait_for_health() {
  local container="$1"
  local timeout="${2:-120}"
  local elapsed=0
  info "Waiting for container health ($container)..."
  while [[ "$elapsed" -lt "$timeout" ]]; do
    local health
    health=$(docker inspect --format='{{.State.Health.Status}}' "$container" 2>/dev/null || echo "none")
    case "$health" in
      healthy)
        info "Container is healthy."
        return 0
        ;;
      none|"")
        # No healthcheck configured — just check it's running
        local running
        running=$(docker inspect --format='{{.State.Running}}' "$container" 2>/dev/null || echo "false")
        if [[ "$running" == "true" ]]; then
          info "Container is running (no healthcheck configured)."
          return 0
        fi
        ;;
      unhealthy)
        warn "Container reported unhealthy."
        return 1
        ;;
    esac
    sleep 5
    elapsed=$((elapsed + 5))
    echo -n "."
  done
  echo ""
  warn "Timed out waiting for health after ${timeout}s."
  return 1
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: setup
# ═════════════════════════════════════════════════════════════════════════════

cmd_setup() {
  # ── Parse CLI flags ──
  # Supports fully non-interactive one-liner:
  #   ./vox setup --repo URL --token TOKEN --hostname DOMAIN [--env /path/.env] [--branch main]
  # Or interactive (no flags / partial flags — prompts for the rest)
  IMPORTED_ENV_FILE=""
  CLI_REPO=""
  CLI_TOKEN=""
  CLI_HOSTNAME=""
  CLI_BRANCH=""
  CLI_AUTOPULL="true"

  while [[ $# -gt 0 ]]; do
    case "$1" in
      --repo)     CLI_REPO="$2"; shift 2 ;;
      --token)    CLI_TOKEN="$2"; shift 2 ;;
      --hostname) CLI_HOSTNAME="$2"; shift 2 ;;
      --domain)   CLI_HOSTNAME="$2"; shift 2 ;;  # alias
      --env)      IMPORTED_ENV_FILE="$2"; shift 2 ;;
      --branch)   CLI_BRANCH="$2"; shift 2 ;;
      --autopull) CLI_AUTOPULL="$2"; shift 2 ;;
      --auto-install) CLI_AUTO_INSTALL="$2"; shift 2 ;;
      --skip-gpu) SKIP_GPU="true"; shift ;;
      *)
        # Bare arg — check if it's a file (drag-and-drop .env)
        local cleaned
        cleaned=$(echo "$1" | sed "s/^['\"]//;s/['\"]$//;s/^[[:space:]]*//;s/[[:space:]]*$//")
        if [[ -f "$cleaned" ]]; then
          IMPORTED_ENV_FILE="$cleaned"
        fi
        shift
        ;;
    esac
  done

  # Determine if we can run fully non-interactive
  local AUTO_MODE="false"
  if [[ -n "$CLI_REPO" ]] && [[ -n "$CLI_TOKEN" ]] && [[ -n "$CLI_HOSTNAME" ]]; then
    AUTO_MODE="true"
  fi

  banner "vox — Deploy Any Repo"

  info "Checking prerequisites..."

  # Decide whether we may interactively prompt for sudo. In AUTO_MODE we
  # refuse to block; otherwise we ask once and cache the credential.
  local SUDO_MODE="interactive"
  [[ "$AUTO_MODE" == "true" ]] && SUDO_MODE="auto"

  # ── Auto-install all dependencies ──

  # Track which dependencies actually need root so we only ask for sudo if
  # something is missing. Privileged steps requested while sudo is unavailable
  # will warn and skip rather than hang.
  local NEEDS_ROOT="false"

  # Docker
  if command -v docker &>/dev/null; then
    info "Docker: $(docker --version | head -c 60)"
  else
    NEEDS_ROOT="true"
    ensure_sudo "$SUDO_MODE" || true
    info "Installing Docker..."
    curl -fsSL https://get.docker.com | sh
    sudo_run 30 usermod -aG docker "$USER" || true
    info "Docker installed."
  fi

  # Docker Compose
  if docker compose version &>/dev/null 2>&1; then
    COMPOSE_CMD="docker compose"
    info "Docker Compose: OK"
  elif command -v docker-compose &>/dev/null; then
    COMPOSE_CMD="docker-compose"
    info "Docker Compose: OK"
  else
    NEEDS_ROOT="true"
    ensure_sudo "$SUDO_MODE" || true
    info "Installing Docker Compose..."
    sudo_run 300 apt-get update -qq || true
    sudo_run 300 apt-get install -y -qq docker-compose-plugin || true
    COMPOSE_CMD="docker compose"
  fi

  # Git
  if command -v git &>/dev/null; then
    info "git: OK"
  else
    NEEDS_ROOT="true"
    ensure_sudo "$SUDO_MODE" || true
    info "Installing git..."
    sudo_run 300 apt-get update -qq || true
    sudo_run 300 apt-get install -y -qq git || true
    if ! command -v git &>/dev/null; then
      err "Failed to install git."
      exit 1
    fi
    info "git: installed"
  fi

  # curl (needed for cloudflared download inside Docker build)
  if ! command -v curl &>/dev/null; then
    NEEDS_ROOT="true"
    ensure_sudo "$SUDO_MODE" || true
    info "Installing curl..."
    sudo_run 300 apt-get update -qq || true
    sudo_run 300 apt-get install -y -qq curl || true
  fi

  # python3 (needed for package.json parsing and config)
  if ! command -v python3 &>/dev/null; then
    NEEDS_ROOT="true"
    ensure_sudo "$SUDO_MODE" || true
    info "Installing python3..."
    sudo_run 300 apt-get update -qq || true
    sudo_run 300 apt-get install -y -qq python3 || true
  fi

  # NVIDIA Container Toolkit (GPU passthrough)
  # Fully idempotent and never blocks: we read /etc/docker/daemon.json directly
  # (no docker-daemon roundtrip required) so we can detect "already configured"
  # without needing the user to be in the docker group, and every privileged
  # call has a hard timeout so an unattended deploy can never hang here.
  if [[ "${SKIP_GPU:-false}" == "true" ]]; then
    info "GPU configuration skipped (SKIP_GPU=true)."
  elif command -v nvidia-smi &>/dev/null; then
    # Cheap, root-free check: is the nvidia runtime already wired into docker?
    local NVIDIA_RUNTIME_CONFIGURED="false"
    if [ -r /etc/docker/daemon.json ] \
       && grep -q '"nvidia"' /etc/docker/daemon.json 2>/dev/null; then
      NVIDIA_RUNTIME_CONFIGURED="true"
    elif docker info --format '{{json .Runtimes}}' 2>/dev/null | grep -qi nvidia; then
      NVIDIA_RUNTIME_CONFIGURED="true"
    fi

    if [[ "$NVIDIA_RUNTIME_CONFIGURED" == "true" ]] && command -v nvidia-ctk &>/dev/null; then
      info "NVIDIA GPU + container toolkit: OK"
    elif command -v nvidia-ctk &>/dev/null; then
      NEEDS_ROOT="true"
      if ensure_sudo "$SUDO_MODE"; then
        info "NVIDIA Container Toolkit present — configuring docker runtime..."
        if sudo_run 60 nvidia-ctk runtime configure --runtime=docker; then
          if sudo_run 90 systemctl restart docker; then
            info "NVIDIA Container Toolkit configured."
          else
            warn "docker restart failed or timed out — restart manually: sudo systemctl restart docker"
          fi
        else
          warn "nvidia-ctk runtime configure failed — continuing without GPU passthrough."
        fi
      else
        warn "Skipping GPU runtime configuration (no sudo). Re-run without --auto or set SKIP_GPU=true to silence this."
      fi
    else
      NEEDS_ROOT="true"
      if ensure_sudo "$SUDO_MODE"; then
        info "NVIDIA GPU detected — installing container toolkit..."
        # Only fetch the keyring if it does not already exist. Use --batch --yes
        # so gpg never prompts (a previous silent hang was caused by this).
        if [ ! -s /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg ]; then
          curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey 2>/dev/null \
            | sudo_run 60 gpg --batch --yes --dearmor \
                -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
            || true
        fi
        # Only write the apt source list if missing.
        if [ ! -s /etc/apt/sources.list.d/nvidia-container-toolkit.list ]; then
          curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list 2>/dev/null \
            | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
            | sudo_run 30 tee /etc/apt/sources.list.d/nvidia-container-toolkit.list >/dev/null \
            || true
        fi
        sudo_run 300 env DEBIAN_FRONTEND=noninteractive apt-get update -qq </dev/null || true
        sudo_run 600 env DEBIAN_FRONTEND=noninteractive apt-get install -y -qq nvidia-container-toolkit </dev/null || true
        sudo_run 60 nvidia-ctk runtime configure --runtime=docker || true
        sudo_run 90 systemctl restart docker || true
        info "NVIDIA Container Toolkit install attempted (continuing regardless)."
      else
        warn "Skipping GPU toolkit install (no sudo). Re-run without --auto or set SKIP_GPU=true to silence this."
      fi
    fi
  else
    info "No NVIDIA GPU detected — GPU passthrough will be skipped at runtime."
  fi

  # Suppress unused-variable warning under set -u; NEEDS_ROOT is informational.
  : "${NEEDS_ROOT}"

  # ─────────────────────────────────────────────────────────────────────────
  # Step 1: Repository
  # ─────────────────────────────────────────────────────────────────────────
  banner "Step 1 / 5 — Repository"

  WORK_DIR="$(pwd)"
  info "Working directory: $WORK_DIR"
  echo ""

  if [[ -n "$CLI_REPO" ]]; then
    REPO_URL="$CLI_REPO"
    info "Repo: $REPO_URL"
  else
    ask REPO_URL "Git repo URL (or local path)" ""
  fi

  if [[ -n "$CLI_BRANCH" ]]; then
    REPO_BRANCH="$CLI_BRANCH"
  elif [[ "$AUTO_MODE" == "true" ]]; then
    REPO_BRANCH="main"
  else
    ask REPO_BRANCH "Branch" "main"
  fi

  # Derive directory name from URL
  DEFAULT_DIR=$(basename "$REPO_URL" .git 2>/dev/null || echo "app")
  if [[ "$AUTO_MODE" == "true" ]]; then
    REPO_DIR="$DEFAULT_DIR"
  else
    ask REPO_DIR "Local directory name" "$DEFAULT_DIR"
  fi

  REPO_PATH="$WORK_DIR/$REPO_DIR"

  if [[ -d "$REPO_PATH/.git" ]]; then
    info "Repo already exists at $REPO_PATH"
    if confirm "Pull latest from $REPO_BRANCH?"; then
      git -C "$REPO_PATH" fetch origin
      git -C "$REPO_PATH" checkout "$REPO_BRANCH"
      git -C "$REPO_PATH" pull origin "$REPO_BRANCH"
    fi
  elif [[ -d "$REPO_PATH" ]] && [[ ! -d "$REPO_PATH/.git" ]]; then
    # Local path, not a git repo — use as-is
    info "Using existing directory: $REPO_PATH"
  else
    info "Cloning $REPO_URL → $REPO_PATH ..."
    # Force GitHub HTTPS repo URLs to SSH so clone uses loaded SSH keys
    if [[ "$REPO_URL" =~ ^https://github\.com/([^/]+)/([^/]+)$ ]]; then
      REPO_URL="git@github.com:${BASH_REMATCH[1]}/${BASH_REMATCH[2]}.git"
    elif [[ "$REPO_URL" =~ ^https://github\.com/([^/]+)/([^/]+)\.git$ ]]; then
      REPO_URL="git@github.com:${BASH_REMATCH[1]}/${BASH_REMATCH[2]}.git"
    fi
    git clone -b "$REPO_BRANCH" "$(echo "$REPO_URL" | sed -E 's#^https://github\.com/([^/]+)/([^/]+)(\.git)?$#git@github.com:\1/\2.git#')" "$REPO_PATH"
  fi

  # ─────────────────────────────────────────────────────────────────────────
  # Step 2: Auto-Detect
  # ─────────────────────────────────────────────────────────────────────────
  banner "Step 2 / 5 — Project Detection"

  USE_EXISTING_DOCKERFILE="false"

  if detect_project "$REPO_PATH"; then
    echo ""
    box_line "Detection Results"
    box_line ""
    box_line "  Type:     $DETECTED_TYPE"
    box_line "  Image:    $DETECTED_BASE_IMAGE"
    box_line "  Install:  ${DETECTED_INSTALL_CMD:-(none)}"
    box_line "  Build:    ${DETECTED_BUILD_CMD:-(none)}"
    box_line "  Start:    ${DETECTED_START_CMD:-(default entrypoint)}"
    box_line "  Port:     $DETECTED_PORT"
    if [[ -n "$DETECTED_DATA_DIRS" ]]; then
      box_line "  Volumes:  $DETECTED_DATA_DIRS"
    fi
    box_render
    echo ""

    if [[ "$DETECTED_HAS_DOCKERFILE" == "true" ]]; then
      echo ""
      echo "  This repo already has a Dockerfile."
      if confirm "Use the repo's own Dockerfile? (n = generate a new one)"; then
        USE_EXISTING_DOCKERFILE="true"
        # Try to detect EXPOSE port from existing Dockerfile
        local_port=$(grep -i "^EXPOSE" "$REPO_PATH/Dockerfile" 2>/dev/null | head -1 | awk '{print $2}' || true)
        if [[ -n "$local_port" ]]; then
          DETECTED_PORT="$local_port"
          detect "Using port $DETECTED_PORT from existing Dockerfile"
        fi
      fi
    fi

    if [[ "$AUTO_MODE" != "true" ]]; then
      if confirm "Customize these settings?"; then
        ask DETECTED_BASE_IMAGE  "Base Docker image"  "$DETECTED_BASE_IMAGE"
        ask DETECTED_INSTALL_CMD "Install command"     "$DETECTED_INSTALL_CMD"
        ask DETECTED_BUILD_CMD   "Build command"       "$DETECTED_BUILD_CMD"
        ask DETECTED_START_CMD   "Start command"       "$DETECTED_START_CMD"
        ask DETECTED_PORT        "Port"                "$DETECTED_PORT"
        ask DETECTED_DATA_DIRS   "Data dirs (space-separated, for volumes)" "$DETECTED_DATA_DIRS"
        ask AUTO_INSTALL         "Auto-install deps on lockfile change? (true/false)" "true"
      fi
    fi
  else
    # Manual configuration
    echo ""
    box_line "Could not auto-detect project type"
    box_line "Configure manually below"
    box_render
    echo ""

    if [[ "$DETECTED_HAS_DOCKERFILE" == "true" ]]; then
      if confirm "The repo has a Dockerfile. Use it?"; then
        USE_EXISTING_DOCKERFILE="true"
        local_port=$(grep -i "^EXPOSE" "$REPO_PATH/Dockerfile" 2>/dev/null | head -1 | awk '{print $2}' || true)
        DETECTED_PORT="${local_port:-3000}"
        ask DETECTED_PORT "Port" "$DETECTED_PORT"
      else
        ask DETECTED_BASE_IMAGE  "Base Docker image (e.g. node:22-slim, python:3.12-slim)" ""
        ask DETECTED_INSTALL_CMD "Dependency install command (e.g. npm ci, pip install -r requirements.txt)" ""
        ask DETECTED_BUILD_CMD   "Build command (blank if none)" ""
        ask DETECTED_START_CMD   "Start command (e.g. npm start, python app.py)" ""
        ask DETECTED_PORT        "Port the app listens on" "3000"
        ask DETECTED_DATA_DIRS   "Persistent data dirs (blank if none)" ""
        ask AUTO_INSTALL         "Auto-install deps on lockfile change? (true/false)" "true"
      fi
    else
      box_line "Common base images:"
      box_line "  node:22-slim    | python:3.12-slim | golang:1.22-alpine"
      box_line "  ruby:3.3-slim   | php:8.3-apache   | nginx:alpine"
      box_render
      echo ""
      ask DETECTED_BASE_IMAGE  "Base Docker image" ""
      ask DETECTED_INSTALL_CMD "Install command" ""
      ask DETECTED_BUILD_CMD   "Build command (blank if none)" ""
      ask DETECTED_START_CMD   "Start command" ""
      ask DETECTED_PORT        "Port" "3000"
      ask DETECTED_DATA_DIRS   "Persistent data dirs (blank if none)" ""
      ask AUTO_INSTALL         "Auto-install deps on lockfile change? (true/false)" "true"
      DETECTED_IGNORE_PATTERNS=".git\n.env.local"
    fi
  fi

  # ─────────────────────────────────────────────────────────────────────────
  # Step 3: Cloudflare Tunnel
  # ─────────────────────────────────────────────────────────────────────────
  banner "Step 3 / 5 — Cloudflare Tunnel"

  CF_TUNNEL_TOKEN="${CLI_TOKEN:-}"
  CF_HOSTNAME="${CLI_HOSTNAME:-}"
  CF_TUNNEL_ID=""
  CF_CREDENTIALS_FILE=""
  CF_AUTH_METHOD="1"

  # ── Already have token + hostname from flags? Skip all prompts ──
  if [[ -n "$CF_TUNNEL_TOKEN" ]] && [[ -n "$CF_HOSTNAME" ]]; then
    info "Hostname: $CF_HOSTNAME"
    info "Tunnel token: provided via --token"
  else
    # ── Interactive tunnel setup ──
    box_line "Expose your app on a domain you control — no open ports needed."
    box_line "You'll need a tunnel token from the Cloudflare Zero Trust dashboard."
    box_line ""
    box_line "Auth methods:"
    box_line "  1) Tunnel token  (recommended — one string from dashboard)"
    box_line "  2) Credentials file  (JSON from 'cloudflared tunnel create')"
    box_render
    echo ""

    if [[ -z "$CF_HOSTNAME" ]]; then
      ask CF_HOSTNAME "Public hostname (e.g. app.example.com)" ""
    fi
    echo ""
    ask CF_AUTH_METHOD "Auth method [1/2]" "1"

    if [[ "$CF_AUTH_METHOD" == "1" ]]; then
      if [[ -z "$CF_TUNNEL_TOKEN" ]]; then
        ask_secret CF_TUNNEL_TOKEN "Cloudflare Tunnel token" ""
      fi
      if [[ -z "$CF_TUNNEL_TOKEN" ]]; then
        err "Tunnel token is required."
        exit 1
      fi
    else
      ask CF_CREDENTIALS_FILE "Path to tunnel credentials JSON" ""
      if [[ ! -f "$CF_CREDENTIALS_FILE" ]]; then
        err "File not found: $CF_CREDENTIALS_FILE"
        exit 1
      fi
      CF_TUNNEL_ID=$(python3 -c "import json; print(json.load(open('$CF_CREDENTIALS_FILE'))['TunnelID'])" 2>/dev/null || true)
      if [[ -z "$CF_TUNNEL_ID" ]]; then
        ask CF_TUNNEL_ID "Tunnel ID (UUID)" ""
      fi
      info "Tunnel ID: $CF_TUNNEL_ID"
    fi
  fi

  # ─────────────────────────────────────────────────────────────────────────
  # Step 4: Environment Variables
  # ─────────────────────────────────────────────────────────────────────────
  banner "Step 4 / 5 — Environment Variables"

  discover_env_vars "$REPO_PATH"

  # ─────────────────────────────────────────────────────────────────────────
  # Step 5: Generate & Deploy
  # ─────────────────────────────────────────────────────────────────────────
  banner "Step 5 / 5 — Generate & Deploy"

  # Production-oriented Node apps commonly require these at boot. Generate
  # stable values into the env file when the imported env is missing or still
  # contains template placeholders.
  if [[ "$DETECTED_TYPE" == node* ]]; then
    ensure_generated_secret "AUTH_JWT_SECRET" 32
    ensure_generated_secret "SIGNING_KEK_HEX" 32
    ensure_generated_secret "SESSION_SECRET" 32
  fi

  # ── .env → inside repo dir ──
  ENV_FILE="$REPO_PATH/.env"
  info "Writing $ENV_FILE"

  {
    echo "# Generated by vox — $(date -Iseconds)"
    echo ""
    echo "# Cloudflare Tunnel"
    echo "CF_HOSTNAME=$CF_HOSTNAME"
    # TUNNEL_TOKEN is what cloudflared reads from environment
    [[ -n "$CF_TUNNEL_TOKEN" ]] && echo "TUNNEL_TOKEN=$CF_TUNNEL_TOKEN"
    [[ -n "$CF_TUNNEL_ID" ]] && echo "CF_TUNNEL_ID=$CF_TUNNEL_ID"
    echo ""
    echo "# Application"
    for entry in "${ENV_VARS[@]+"${ENV_VARS[@]}"}"; do
      echo "$entry"
    done
  } > "$ENV_FILE"

  # ── Dockerfile ──
  if [[ "$USE_EXISTING_DOCKERFILE" == "true" ]]; then
    info "Using repo's existing Dockerfile"
    # Patch: ensure cloudflared + entrypoint are present even in user Dockerfiles
    if ! grep -q "cloudflared" "$REPO_PATH/Dockerfile" 2>/dev/null; then
      info "Patching Dockerfile: adding cloudflared install"
      # Append cloudflared install + entrypoint before the last CMD/ENTRYPOINT
      local orig_cmd
      orig_cmd=$(grep -E "^(CMD|ENTRYPOINT)" "$REPO_PATH/Dockerfile" | tail -1 || true)
      if [[ -n "$orig_cmd" ]]; then
        # Extract the start command from existing CMD/ENTRYPOINT
        local start_from_dockerfile
        start_from_dockerfile=$(echo "$orig_cmd" | sed 's/^CMD\s*//;s/^ENTRYPOINT\s*//' | sed 's/^\[//;s/\]$//;s/"//g;s/,/ /g')
        # Generate entrypoint with existing start command
        generate_entrypoint "$REPO_PATH/entrypoint.sh" "$start_from_dockerfile" "${DETECTED_PORT:-3000}"
        # Append to Dockerfile: install cloudflared, copy entrypoint, override CMD
        cat >> "$REPO_PATH/Dockerfile" <<'PATCHEOF'

# --- vox: cloudflared + GPU support injected ---
RUN (apk add --no-cache bash ca-certificates curl postgresql-client 2>/dev/null || (apt-get update && apt-get install -y --no-install-recommends bash ca-certificates curl postgresql-client && rm -rf /var/lib/apt/lists/*)) ; \
    curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && \
    chmod +x /usr/local/bin/cloudflared
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
PATCHEOF
        info "Patched: cloudflared + entrypoint added to existing Dockerfile"
      fi
    fi
  else
    DOCKERFILE="$REPO_PATH/Dockerfile"
    info "Writing $DOCKERFILE"
    generate_dockerfile "$REPO_PATH" "$DOCKERFILE"
  fi

  # ── .dockerignore ──
  DOCKERIGNORE="$REPO_PATH/.dockerignore"
  if [[ ! -f "$DOCKERIGNORE" ]]; then
    info "Writing $DOCKERIGNORE"
    echo -e "$DETECTED_IGNORE_PATTERNS" > "$DOCKERIGNORE"
  else
    info "Keeping existing .dockerignore"
  fi

  # ── docker-compose.yml ──
  COMPOSE_FILE="$WORK_DIR/docker-compose.yml"
  if [[ -f "$COMPOSE_FILE" ]]; then
    info "Releasing previous vox containers before regenerating compose"
    compose_release_project_resources
  fi
  info "Writing $COMPOSE_FILE"
  generate_compose "$COMPOSE_FILE" "$REPO_DIR"

  # ── Credentials file tunnel config ──
  CF_CREDS_DEST=""
  if [[ -z "$CF_TUNNEL_TOKEN" ]] && [[ -n "$CF_CREDENTIALS_FILE" ]]; then
    CF_CREDS_DEST="$WORK_DIR/.cloudflared"
    mkdir -p "$CF_CREDS_DEST"
    cp "$CF_CREDENTIALS_FILE" "$CF_CREDS_DEST/credentials.json"
    cat > "$CF_CREDS_DEST/config.yml" <<CFGEOF
tunnel: $CF_TUNNEL_ID
credentials-file: /etc/cloudflared/credentials.json

ingress:
  - hostname: $CF_HOSTNAME
    service: http://app:${DETECTED_PORT}
  - service: http_status:404
CFGEOF
    info "Writing .cloudflared/config.yml"
  fi

  # ── Determine tunnel method string ──
  local tunnel_method="token"
  [[ "$CF_AUTH_METHOD" == "2" ]] && tunnel_method="credentials"

  # ── Save config to .vox/config.json ──
  vox_init_dirs
  vox_save_config \
    "$REPO_DIR" \
    "$REPO_URL" \
    "$REPO_BRANCH" \
    "$REPO_DIR" \
    "$CF_HOSTNAME" \
    "$DETECTED_PORT" \
    "$DETECTED_TYPE" \
    "$DETECTED_BASE_IMAGE" \
    "$DETECTED_INSTALL_CMD" \
    "$DETECTED_BUILD_CMD" \
    "$DETECTED_START_CMD" \
    "$DETECTED_DATA_DIRS" \
    "$tunnel_method" \
    "$USE_EXISTING_DOCKERFILE" \
    "$(date -Iseconds)" \
    "$COMPOSE_CMD" \
    "${AUTO_INSTALL:-}"

  # ── Tag first image for rollback support ──
  local image_tag
  image_tag="${REPO_DIR}:initial-$(date +%Y%m%d%H%M%S)"

  # ── Summary ──
  echo ""
  box_line "Architecture: SINGLE CONTAINER (app + cloudflared tunnel)"
  box_line "Each project is fully isolated — no host-level tunnel config."
  box_line ""
  box_line "Generated files:"
  box_line "  $WORK_DIR/"
  box_line "    docker-compose.yml"
  box_line "    $REPO_DIR/.env"
  if [[ "$USE_EXISTING_DOCKERFILE" != "true" ]]; then
    box_line "    $REPO_DIR/Dockerfile"
    box_line "    $REPO_DIR/entrypoint.sh"
  fi
  box_line "    $REPO_DIR/.dockerignore"
  [[ -n "$CF_CREDS_DEST" ]] && box_line "    .cloudflared/config.yml"
  box_line "    .vox/config.json"
  box_line ""
  box_line "  Stack: $DETECTED_TYPE → port $DETECTED_PORT → https://$CF_HOSTNAME"
  box_render

  echo ""

  if [[ "$AUTO_MODE" == "true" ]] || confirm "Build and start now?"; then
    cd "$WORK_DIR"

    step "Phase 1/2: Build container image"
    if ! compose_build; then
      err "Initial build failed — not starting services. Fix errors above and re-run."
      exit 1
    fi

    step "Phase 2/2: Start services"
    if ! compose_up; then
      err "Service startup failed after successful build."
      err "Run './vox logs' to diagnose."
      exit 1
    fi

    # Log initial deploy
    vox_log_deploy "success" "$image_tag"

    echo ""
    banner "Live"

    box_line "Single container running: app + cloudflared tunnel"
    box_line "Public: https://${CF_HOSTNAME} (tunnel from inside container)"
    box_line "No ports exposed to host — fully isolated"
    box_line ""
    box_line "Commands:"
    box_line "  ./vox logs --follow   # follow logs"
    box_line "  ./vox status          # container status"
    box_line "  ./vox stop            # stop services"
    box_line "  ./vox deploy          # rebuild + redeploy"
    box_line "  ./vox rollback        # roll back to previous"
    box_line ""
    box_line "Edit $REPO_DIR/.env and run './vox deploy' to apply."
    box_render
  else
    echo ""
    info "When ready:"
    echo "    ./vox deploy"
  fi

  # ── Auto-start watcher (default on, disable with --autopull false) ──
  if [[ "$CLI_AUTOPULL" == "true" ]]; then
    info "Starting autopull watcher (monitors repo for changes)..."
    # Prefer the systemd-managed watcher so it survives reboots and auto-
    # restarts on crash. Fall back to the detached background loop if systemd
    # is unavailable or install fails (e.g. no passwordless sudo).
    local installed_service=0
    if command -v systemctl >/dev/null 2>&1; then
      if cmd_watch_install_service; then
        installed_service=1
      else
        warn "Could not install systemd service — falling back to detached watcher."
      fi
    fi
    if [[ "$installed_service" == "0" ]]; then
      cmd_watch_start
      info "For reboot-persistent auto-deploy, run: ./vox watch install-service"
    fi
    info "Disable with: ./vox watch stop   |   Skip at setup: --autopull false"
  fi

  banner "Done"
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: deploy
# ═════════════════════════════════════════════════════════════════════════════

cmd_deploy() {
  vox_load_config
  banner "vox deploy"

  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"

  # 1. Pull latest code
  if [[ -d "$REPO_PATH/.git" ]]; then
    info "Pulling latest from $CFG_REPO_BRANCH..."
    git -C "$REPO_PATH" pull origin "$CFG_REPO_BRANCH"
  else
    info "No git repo at $REPO_PATH — skipping pull"
  fi

  # 1b. Auto-install dependencies if lockfiles changed (or forced)
  if [[ "${CFG_AUTO_INSTALL:-}" == "true" ]] || [[ "${CLI_AUTO_INSTALL:-}" == "true" ]]; then
    if ! run_install_if_needed "$REPO_PATH" "$CFG_INSTALL_CMD" "${CLI_AUTO_INSTALL:-}"; then
      err "Dependency install failed — aborting deploy to avoid broken build."
      exit 1
    fi
  fi

  # 2. Tag current running image as rollback target
  local ts
  ts=$(date +%Y%m%d%H%M%S)
  local rollback_tag="${CFG_REPO_DIR}:rollback-${ts}"
  local container_name
  container_name=$(echo "$CFG_REPO_DIR" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-*$//')
  local app_container="${container_name}"

  local current_image
  current_image=$(docker inspect --format='{{.Image}}' "$app_container" 2>/dev/null || true)
  if [[ -n "$current_image" ]]; then
    info "Tagging current image as rollback: $rollback_tag"
    docker tag "$current_image" "$rollback_tag" 2>/dev/null || true
  fi

  # 3. Build
  cd "$WORK_DIR"
  step "Phase 1/3: Build new image"
  if ! compose_build; then
    err "Build failed — current running image is unchanged."
    vox_log_deploy "build-failed" "$rollback_tag"
    exit 1
  fi

  # 4. Zero-downtime restart
  step "Phase 2/3: Restart services with new image"
  if ! compose_up; then
    err "Restart failed after successful build."
    vox_log_deploy "restart-failed" "$rollback_tag"
    exit 1
  fi

  step "Phase 3/3: Wait for healthcheck"

  # 5. Wait for healthcheck
  local git_sha=""
  if [[ -d "$REPO_PATH/.git" ]]; then
    git_sha=$(git -C "$REPO_PATH" rev-parse --short HEAD 2>/dev/null || true)
  fi

  if wait_for_health "$app_container" 120; then
    vox_log_deploy "success" "$rollback_tag"
    echo "$(git -C "$REPO_PATH" rev-parse HEAD 2>/dev/null || true)" > "$VOX_DIR/deployed.sha" 2>/dev/null || true
    box_line "Deploy successful"
    box_line "  Git SHA: ${git_sha:-(unknown)}"
    box_line "  Image:   $rollback_tag"
    box_line "  URL:     https://$CFG_HOSTNAME"
    box_render
  else
    vox_log_deploy "failed" "$rollback_tag"
    err "Deploy completed but healthcheck did not pass."
    info "Run './vox logs' to diagnose."
    exit 1
  fi
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: logs
# ═════════════════════════════════════════════════════════════════════════════

cmd_logs() {
  vox_load_config
  WORK_DIR="$(pwd)"
  cd "$WORK_DIR"
  if [[ "${1:-}" == "--follow" ]] || [[ "${1:-}" == "-f" ]]; then
    $COMPOSE_CMD logs -f
  else
    $COMPOSE_CMD logs --tail=100
  fi
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: status
# ═════════════════════════════════════════════════════════════════════════════

cmd_status() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"

  local git_sha=""
  if [[ -d "$REPO_PATH/.git" ]]; then
    git_sha=$(git -C "$REPO_PATH" rev-parse --short HEAD 2>/dev/null || true)
  fi

  local container_name
  container_name=$(echo "$CFG_REPO_DIR" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-*$//')
  local ctr="${container_name}"

  local ctr_status="not running"
  local ctr_health="n/a"
  local ctr_uptime=""
  local ctr_image=""
  if docker inspect "$ctr" &>/dev/null 2>&1; then
    ctr_status=$(docker inspect --format='{{.State.Status}}' "$ctr" 2>/dev/null || echo "unknown")
    ctr_health=$(docker inspect --format='{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}' "$ctr" 2>/dev/null || echo "n/a")
    ctr_uptime=$(docker inspect --format='{{.State.StartedAt}}' "$ctr" 2>/dev/null || true)
    ctr_image=$(docker inspect --format='{{.Config.Image}}' "$ctr" 2>/dev/null || true)
  fi

  # Find last deploy
  local last_deploy=""
  if [[ -d "$VOX_DEPLOYS" ]]; then
    local latest
    latest=$(ls "$VOX_DEPLOYS"/*.json 2>/dev/null | sort | tail -1 || true)
    if [[ -n "$latest" ]]; then
      last_deploy=$(python3 -c "
import json
d = json.load(open('$latest'))
print(d.get('timestamp','') + ' [' + d.get('status','') + ']')
" 2>/dev/null || true)
    fi
  fi

  banner "vox status"
  box_line "Project:      $CFG_PROJECT_NAME"
  box_line "Type:         $CFG_TYPE"
  box_line "Hostname:     https://$CFG_HOSTNAME"
  box_line ""
  box_line "Container:    $ctr_status  (health: $ctr_health)"
  box_line "  app + cloudflared tunnel running inside single container"
  box_line ""
  box_line "Image:        ${ctr_image:-(none)}"
  box_line "Git SHA:      ${git_sha:-(unknown)}"
  box_line "Started:      ${ctr_uptime:-(not running)}"
  box_line "Last deploy:  ${last_deploy:-(none)}"
  box_render
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: stop / start / restart
# ═════════════════════════════════════════════════════════════════════════════

cmd_stop() {
  vox_load_config
  WORK_DIR="$(pwd)"
  cd "$WORK_DIR"
  compose_down
}

cmd_start() {
  vox_load_config
  WORK_DIR="$(pwd)"
  cd "$WORK_DIR"
  compose_up
}

cmd_restart() {
  vox_load_config
  WORK_DIR="$(pwd)"
  cd "$WORK_DIR"
  compose_down
  compose_up
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: rollback [n]
# ═════════════════════════════════════════════════════════════════════════════

cmd_rollback() {
  vox_load_config
  WORK_DIR="$(pwd)"

  local steps="${1:-1}"

  # List rollback images from deploy history
  if [[ ! -d "$VOX_DEPLOYS" ]]; then
    err "No deploy history found in $VOX_DEPLOYS"
    exit 1
  fi

  local deploy_files
  deploy_files=$(ls "$VOX_DEPLOYS"/*.json 2>/dev/null | sort -r || true)
  if [[ -z "$deploy_files" ]]; then
    err "No deploys recorded yet."
    exit 1
  fi

  # Collect image tags from history (most recent first)
  local tags=()
  while IFS= read -r f; do
    local tag
    tag=$(python3 -c "
import json
d = json.load(open('$f'))
t = d.get('image_tag','')
if t:
    print(t)
" 2>/dev/null || true)
    [[ -n "$tag" ]] && tags+=("$tag")
  done <<< "$deploy_files"

  if [[ "${#tags[@]}" -eq 0 ]]; then
    err "No rollback image tags found in deploy history."
    exit 1
  fi

  # n-th step: index steps-1 (0 = most recent)
  local idx=$((steps - 1))
  if [[ "$idx" -ge "${#tags[@]}" ]]; then
    err "Only ${#tags[@]} rollback(s) available; cannot roll back $steps steps."
    exit 1
  fi

  local rollback_tag="${tags[$idx]}"

  # Check image actually exists
  if ! docker image inspect "$rollback_tag" &>/dev/null 2>&1; then
    err "Image '$rollback_tag' not found locally. Cannot roll back to it."
    exit 1
  fi

  info "Rolling back to: $rollback_tag"

  cd "$WORK_DIR"
  step "Phase 1/3: Stop running services"
  compose_down

  # Temporarily override the compose image — use docker tag to re-point
  step "Phase 2/3: Re-tag rollback image as current"
  local container_name
  container_name=$(echo "$CFG_REPO_DIR" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-*$//')
  local current_tag="${CFG_REPO_DIR}:latest"
  docker tag "$rollback_tag" "$current_tag" 2>/dev/null || true

  step "Phase 3/3: Start services from rollback image"
  compose_up

  local ts
  ts=$(date -Iseconds)
  vox_log_deploy "rollback:$rollback_tag" "$rollback_tag"

  info "Rollback complete to $rollback_tag"
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: env / env set / env unset
# ═════════════════════════════════════════════════════════════════════════════

cmd_env() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  local env_file="$REPO_PATH/.env"

  local subcmd="${1:-}"

  case "$subcmd" in
    set)
      # ./vox env set KEY=VALUE
      local kv="${2:-}"
      if [[ -z "$kv" ]] || [[ "$kv" != *"="* ]]; then
        err "Usage: ./vox env set KEY=VALUE"
        exit 1
      fi
      local key="${kv%%=*}"
      local value="${kv#*=}"

      if [[ ! -f "$env_file" ]]; then
        touch "$env_file"
      fi

      # Update or append
      if grep -q "^${key}=" "$env_file" 2>/dev/null; then
        # Replace existing
        python3 - <<PYEOF
import re
with open('$env_file', 'r') as f:
    content = f.read()
content = re.sub(r'^${key}=.*$', '${key}=${value}', content, flags=re.MULTILINE)
with open('$env_file', 'w') as f:
    f.write(content)
PYEOF
        info "Updated $key in $env_file"
      else
        echo "${key}=${value}" >> "$env_file"
        info "Added $key to $env_file"
      fi

      # Redeploy
      cd "$WORK_DIR"
      compose_up
      info "Services restarted with updated env."
      ;;

    unset)
      # ./vox env unset KEY
      local key="${2:-}"
      if [[ -z "$key" ]]; then
        err "Usage: ./vox env unset KEY"
        exit 1
      fi

      if [[ ! -f "$env_file" ]]; then
        err "No .env file found at $env_file"
        exit 1
      fi

      python3 - <<PYEOF
import re
with open('$env_file', 'r') as f:
    lines = f.readlines()
lines = [l for l in lines if not re.match(r'^${key}=', l)]
with open('$env_file', 'w') as f:
    f.writelines(lines)
PYEOF
      info "Removed $key from $env_file"

      # Redeploy
      cd "$WORK_DIR"
      compose_up
      info "Services restarted with updated env."
      ;;

    "")
      # ./vox env — show all vars, masking secrets
      if [[ ! -f "$env_file" ]]; then
        err "No .env file found at $env_file"
        exit 1
      fi

      banner "Environment: $CFG_REPO_DIR"
      while IFS= read -r line; do
        [[ "$line" =~ ^[[:space:]]*# ]] && continue
        [[ -z "${line// /}" ]] && continue
        if [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*) ]]; then
          local k="${BASH_REMATCH[1]}"
          local v="${BASH_REMATCH[2]}"
          if [[ "$k" =~ (SECRET|TOKEN|PASSWORD|KEY|PRIVATE|AUTH) ]]; then
            echo -e "  ${CYAN}${k}${NC}=${DIM}****${NC}"
          else
            echo -e "  ${CYAN}${k}${NC}=${v}"
          fi
        fi
      done < "$env_file"
      ;;

    *)
      err "Unknown env subcommand: $subcmd"
      err "Usage: ./vox env [set KEY=VALUE | unset KEY]"
      exit 1
      ;;
  esac
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: history
# ═════════════════════════════════════════════════════════════════════════════

cmd_history() {
  vox_load_config

  if [[ ! -d "$VOX_DEPLOYS" ]]; then
    info "No deploy history yet."
    return 0
  fi

  local files
  files=$(ls "$VOX_DEPLOYS"/*.json 2>/dev/null | sort -r | head -20 || true)
  if [[ -z "$files" ]]; then
    info "No deploys recorded yet."
    return 0
  fi

  banner "Deploy History"
  printf "  %-30s %-10s %-40s %s\n" "Timestamp" "SHA" "Image Tag" "Status"
  printf "  %-30s %-10s %-40s %s\n" "─────────────────────────────" "─────────" "───────────────────────────────────────" "──────"

  while IFS= read -r f; do
    python3 - <<PYEOF
import json
d = json.load(open('$f'))
ts  = d.get('timestamp','')[:19]
sha = d.get('git_sha','')[:9]
img = d.get('image_tag','')[:39]
st  = d.get('status','')
print(f"  {ts:<30} {sha:<10} {img:<40} {st}")
PYEOF
  done <<< "$files"
  echo ""
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: watch
# ═════════════════════════════════════════════════════════════════════════════

deploy_with_rollback() {
  # Deploy and auto-rollback to previous image on failure.
  # Used by the watch loop for safe unattended deploys.
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  COMPOSE_CMD="${CFG_COMPOSE_CMD:-docker compose}"

  local container_name
  container_name=$(echo "$CFG_REPO_DIR" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-*$//')

  # Save current state for rollback
  local pre_sha=""
  pre_sha=$(git -C "$REPO_PATH" rev-parse HEAD 2>/dev/null || true)
  local pre_image=""
  pre_image=$(docker inspect --format='{{.Image}}' "$container_name" 2>/dev/null || true)
  local rollback_tag="${CFG_REPO_DIR}:rollback-$(date +%Y%m%d%H%M%S)"
  if [[ -n "$pre_image" ]]; then
    docker tag "$pre_image" "$rollback_tag" 2>/dev/null || true
  fi

  # Pull — keep stderr visible so the user sees why a pull failed (auth, etc.)
  info "Pulling latest from $CFG_REPO_BRANCH..."
  if ! git -C "$REPO_PATH" pull origin "$CFG_REPO_BRANCH"; then
    warn "Git pull failed — aborting deploy, keeping current version."
    return 1
  fi

  local post_sha="" post_sha_full=""
  post_sha=$(git -C "$REPO_PATH" rev-parse --short HEAD 2>/dev/null || true)
  post_sha_full=$(git -C "$REPO_PATH" rev-parse HEAD 2>/dev/null || true)

  # When a deploy fails below we record post_sha_full into
  # .vox/last-failed.sha so watch_check_once can refuse to redeploy the
  # same broken commit on every tick. Helper inlined here so each failure
  # path is a one-liner.
  _vox_mark_failed_sha() {
    [[ -n "$post_sha_full" ]] || return 0
    mkdir -p "$VOX_DIR" 2>/dev/null || true
    echo "$post_sha_full" > "$VOX_DIR/last-failed.sha" 2>/dev/null || true
  }

  # Auto-install dependencies if lockfiles changed (or forced)
  if [[ "${CFG_AUTO_INSTALL:-}" == "true" ]] || [[ "${CLI_AUTO_INSTALL:-}" == "true" ]]; then
    if ! run_install_if_needed "$REPO_PATH" "$CFG_INSTALL_CMD" "${CLI_AUTO_INSTALL:-}"; then
      warn "Dependency install failed — aborting auto-deploy, keeping current version."
      _vox_mark_failed_sha
      return 1
    fi
  fi

  # Build — stream full output so build failures are diagnosable
  step "Auto-deploy phase 1/2: Build ($post_sha)"
  if ! compose_build; then
    warn "Build failed — rolling back to $pre_sha..."
    git -C "$REPO_PATH" reset --hard "$pre_sha" || true
    vox_log_deploy "build-failed" "$rollback_tag"
    _vox_mark_failed_sha
    return 1
  fi

  # Restart — stream output so start failures are visible
  step "Auto-deploy phase 2/2: Restart services"
  if ! compose_up; then
    warn "Start failed after successful build — rolling back to $pre_sha..."
    git -C "$REPO_PATH" reset --hard "$pre_sha" || true
    compose_build || true
    compose_up || true
    vox_log_deploy "start-failed" "$rollback_tag"
    _vox_mark_failed_sha
    return 1
  fi

  # Healthcheck
  if wait_for_health "$container_name" 120; then
    vox_log_deploy "success" "$rollback_tag"
    # Record the currently-deployed SHA so the watch loop can detect drift
    # between local HEAD and what's actually live, even when local == origin
    # (i.e. when pushes are made from the same clone the watcher is in).
    echo "$(git -C "$REPO_PATH" rev-parse HEAD 2>/dev/null || true)" > "$VOX_DIR/deployed.sha" 2>/dev/null || true
    # Clear the failure marker — this SHA is now known-good.
    rm -f "$VOX_DIR/last-failed.sha" "$VOX_DIR/last-failed.notified" 2>/dev/null || true
    info "Deploy successful ($post_sha) — https://$CFG_HOSTNAME"
    return 0
  else
    # Healthcheck failed — rollback (keep output visible during recovery)
    warn "Healthcheck failed — rolling back to $pre_sha..."
    git -C "$REPO_PATH" reset --hard "$pre_sha" || true
    compose_build || true
    compose_up || true
    vox_log_deploy "rollback" "$rollback_tag"
    _vox_mark_failed_sha
    warn "Rolled back to $pre_sha"
    return 1
  fi
}

watch_log() {
  printf '[%s] %s\n' "$(date -u +%FT%TZ)" "$*"
}

# Build the systemd unit name (one service per project directory).
watch_sanitize_name() {
  local raw="${1:-vox}"
  local safe
  safe=$(echo "$raw" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9-' '-' | sed 's/-\+/-/g;s/^-\+//;s/-\+$//')
  [[ -z "$safe" ]] && safe="vox"
  echo "$safe"
}

watch_service_name() {
  local project="${CFG_PROJECT_NAME:-$(basename "$(pwd)")}"
  local safe
  safe=$(watch_sanitize_name "$project")
  echo "vox-watch-${safe}"
}

watch_service_candidates() {
  local primary stored fallback
  primary="$(watch_service_name).service"
  echo "$primary"

  if [[ -f "$VOX_DIR/watch.unit" ]]; then
    stored=$(tr -d '[:space:]' < "$VOX_DIR/watch.unit" 2>/dev/null || true)
    if [[ -n "$stored" ]]; then
      [[ "$stored" != *.service ]] && stored="${stored}.service"
      [[ "$stored" != "$primary" ]] && echo "$stored"
    fi
  fi

  fallback="vox-watch-$(watch_sanitize_name "$(basename "$(pwd)")").service"
  [[ "$fallback" != "$primary" ]] && echo "$fallback"
}

systemd_unit_known() {
  local unit="$1"
  systemctl list-unit-files "$unit" --no-pager --no-legend 2>/dev/null | awk '{print $1}' | grep -Fxq "$unit" && return 0
  systemctl list-units --all "$unit" --no-pager --no-legend 2>/dev/null | awk '{print $1}' | grep -Fxq "$unit"
}

vox_script_path() {
  # The systemd unit must re-invoke THIS exact script — the one that wrote the
  # unit and owns .vox/. Earlier versions preferred $REPO_PATH/vox, which
  # silently picked up any stale copy of vox that happened to be checked into
  # the deployed repo. That stale copy then ran from systemd instead of the
  # patched parent, producing a confusing zombie watcher that exited 0 on
  # every tick and never deployed anything.
  local self
  self=$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || true)
  if [[ -n "$self" ]] && [[ -x "$self" ]]; then
    echo "$self"
    return 0
  fi
  local work_script="$WORK_DIR/vox"
  if [[ -x "$work_script" ]]; then
    echo "$work_script"
    return 0
  fi
  if [[ -n "${REPO_PATH:-}" ]] && [[ -x "$REPO_PATH/vox" ]]; then
    echo "$REPO_PATH/vox"
    return 0
  fi
  echo "$work_script"
}

# Run one fetch-and-deploy-if-needed check. Stays quiet when there is nothing
# to do so it is safe to call frequently from cron / webhooks.
#   0 = no change or successful deploy
#   1 = deploy was triggered but failed (and rolled back)
#   2 = fetch/comparison failed (transient — retry next tick)
watch_check_once() {
  if [[ ! -d "$REPO_PATH/.git" ]]; then
    watch_log "[autopull] skip: $REPO_PATH is not a git checkout"
    return 2
  fi

  # Fetch the tracked branch. Capture stderr for visibility when it fails
  # (network hiccup, expired creds, upstream missing, etc).
  local fetch_err
  if ! fetch_err=$(git -C "$REPO_PATH" fetch origin "$CFG_REPO_BRANCH" --quiet 2>&1); then
    watch_log "[autopull] fetch failed: ${fetch_err:-unknown error}"
    return 2
  fi

  local local_sha remote_sha deployed_sha
  local_sha=$(git -C "$REPO_PATH" rev-parse HEAD 2>/dev/null || true)
  remote_sha=$(git -C "$REPO_PATH" rev-parse "origin/$CFG_REPO_BRANCH" 2>/dev/null || true)
  deployed_sha=""
  if [[ -f "$VOX_DIR/deployed.sha" ]]; then
    deployed_sha=$(cat "$VOX_DIR/deployed.sha" 2>/dev/null | tr -d '[:space:]' || true)
  fi

  # First-run bootstrap: seed deployed.sha to the current HEAD so the
  # local-vs-deployed branch below can detect drift from the very first push.
  # Without this, a push from this same clone (where local == origin after the
  # push) would be invisible on the first tick after the watcher starts.
  if [[ -z "$deployed_sha" ]] && [[ -n "$local_sha" ]]; then
    echo "$local_sha" > "$VOX_DIR/deployed.sha" 2>/dev/null || true
    deployed_sha="$local_sha"
  fi

  local trigger=""
  if [[ -n "$local_sha" ]] && [[ -n "$remote_sha" ]] && [[ "$local_sha" != "$remote_sha" ]]; then
    local behind
    behind=$(git -C "$REPO_PATH" rev-list --count "HEAD..origin/$CFG_REPO_BRANCH" 2>/dev/null || echo 0)
    trigger="origin-ahead (${behind} commit(s) behind ${CFG_REPO_BRANCH})"
  elif [[ -n "$local_sha" ]] && [[ -n "$deployed_sha" ]] && [[ "$local_sha" != "$deployed_sha" ]]; then
    trigger="local-vs-deployed drift (local=${local_sha:0:8} deployed=${deployed_sha:0:8})"
  fi

  if [[ -z "$trigger" ]]; then
    return 0
  fi

  # ── Stuck-SHA guard ──
  # deploy_with_rollback writes .vox/last-failed.sha (full SHA) on every
  # failure path. If origin still points at that exact SHA, refuse to
  # redeploy on this tick — wait for origin to advance past the broken
  # commit (or for the operator to delete the marker). Without this we
  # burned an hour of CPU rebuilding the same broken commit every 15s.
  # Logged once per stuck SHA via .vox/last-failed.notified, not every
  # tick, so the watcher log stays readable.
  local last_failed=""
  [[ -f "$VOX_DIR/last-failed.sha" ]] && last_failed=$(cat "$VOX_DIR/last-failed.sha" 2>/dev/null | tr -d '[:space:]' || true)
  if [[ -n "$last_failed" ]] && [[ "$last_failed" == "$remote_sha" ]]; then
    local notified=""
    [[ -f "$VOX_DIR/last-failed.notified" ]] && notified=$(cat "$VOX_DIR/last-failed.notified" 2>/dev/null | tr -d '[:space:]' || true)
    if [[ "$notified" != "$last_failed" ]]; then
      watch_log "[autopull] holding back: origin ${last_failed:0:8} previously failed to deploy — waiting for a new commit (or 'rm $VOX_DIR/last-failed.sha') before retrying. See $VOX_DIR/build.log for the failure."
      echo "$last_failed" > "$VOX_DIR/last-failed.notified" 2>/dev/null || true
    fi
    return 0
  fi

  watch_log "[autopull] $trigger — deploying..."
  if deploy_with_rollback; then
    watch_log "[autopull] deploy ok HEAD=$(git -C "$REPO_PATH" rev-parse --short HEAD 2>/dev/null)"
    return 0
  else
    watch_log "[autopull] deploy failed, rolled back"
    return 1
  fi
}

watch_loop() {
  local interval="${VOX_WATCH_INTERVAL:-15}"
  watch_log "watcher PID $$ started, interval=${interval}s, repo=$REPO_PATH, branch=$CFG_REPO_BRANCH"
  # Propagate SIGTERM from systemd / `watch stop` into a clean exit.
  trap 'watch_log "watcher received signal, exiting"; exit 0' TERM INT HUP
  while true; do
    watch_check_once || true
    # Plain sleep — trap handlers still fire after sleep returns, so shutdown
    # latency is bounded by $interval. systemd TimeoutStopSec=15 covers it.
    sleep "$interval" || true
  done
}

cmd_watch_stop() {
  vox_maybe_load_config || true

  # Stop systemd-managed instance if present...
  local svc seen_units=" "
  while IFS= read -r svc; do
    [[ -z "$svc" ]] && continue
    [[ "$seen_units" == *" $svc "* ]] && continue
    seen_units="${seen_units}${svc} "
    if systemd_unit_known "$svc"; then
      # Try non-interactive first; if that fails, escalate to an interactive
      # prompt so the user can actually stop the service when they ask to.
      ensure_sudo auto || true
      if ! sudo_run 15 systemctl stop "$svc" >/dev/null 2>&1; then
        ensure_sudo interactive || true
        if ! sudo_run 15 systemctl stop "$svc" >/dev/null 2>&1; then
          warn "Could not stop systemd service $svc. Try: sudo systemctl stop $svc"
        else
          info "Stopped systemd service $svc."
        fi
      else
        info "Stopped systemd service $svc."
      fi
    fi
  done < <(watch_service_candidates)

  # ...then the local pidfile-managed instance.
  local pidfile="$VOX_DIR/watch.pid"
  if [[ -f "$pidfile" ]]; then
    local pid
    pid=$(cat "$pidfile" 2>/dev/null || true)
    if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
      kill -TERM "$pid" 2>/dev/null || true
      # Give it a couple of seconds to exit cleanly.
      local i
      for i in 1 2 3 4 5; do
        if ! kill -0 "$pid" 2>/dev/null; then break; fi
        sleep 1
      done
      if kill -0 "$pid" 2>/dev/null; then
        kill -KILL "$pid" 2>/dev/null || true
      fi
      rm -f "$pidfile"
      info "Watcher stopped (PID $pid)."
    else
      rm -f "$pidfile"
      info "Watcher was not running (stale PID)."
    fi
  fi
  return 0
}

cmd_watch_status() {
  vox_maybe_load_config || true

  local any=0
  local svc seen_units=" "
  while IFS= read -r svc; do
    [[ -z "$svc" ]] && continue
    [[ "$seen_units" == *" $svc "* ]] && continue
    seen_units="${seen_units}${svc} "
    if systemd_unit_known "$svc"; then
      any=1
      local state
      state=$(systemctl is-active "$svc" 2>/dev/null || true)
      local enabled
      enabled=$(systemctl is-enabled "$svc" 2>/dev/null || true)
      info "systemd: $svc — active=${state:-unknown} enabled=${enabled:-unknown}"
    fi
  done < <(watch_service_candidates)

  local pidfile="$VOX_DIR/watch.pid"
  if [[ -f "$pidfile" ]] && kill -0 "$(cat "$pidfile" 2>/dev/null)" 2>/dev/null; then
    any=1
    info "local: watcher running (PID $(cat "$pidfile"))."
  fi

  if [[ "$any" == "0" ]]; then
    info "Watcher not running."
  fi
  return 0
}

# Reconciler: detect "watcher should be alive but isn't" and self-heal silently
# where possible. Designed to be called at the top of any non-destructive
# command (deploy, status, start, restart, watch) without slowing it down or
# prompting for credentials. Returns 0 always; never blocks the caller.
#
#   - Clean up stale pidfile from a dead detached watcher.
#   - If a systemd unit is installed but inactive, try a non-interactive
#     `sudo -n systemctl start` (silently no-ops if sudo creds aren't cached).
#   - If no persistent watcher exists at all (no systemd unit, no live pidfile),
#     print a one-line actionable warning. We do NOT auto-install systemd here
#     because that needs sudo and would interrupt every `./vox deploy`.
watch_ensure_alive() {
  # Only meaningful once setup has run.
  vox_maybe_load_config || return 0
  [[ -z "${CFG_PROJECT_NAME:-}" ]] && return 0
  vox_init_dirs 2>/dev/null || return 0

  local pidfile="$VOX_DIR/watch.pid"
  local svc
  svc=$(watch_service_name)

  # 1. Reap any stale pidfile from a dead detached watcher.
  if [[ -f "$pidfile" ]]; then
    local existing_pid
    existing_pid=$(cat "$pidfile" 2>/dev/null || true)
    if [[ -z "$existing_pid" ]] || ! kill -0 "$existing_pid" 2>/dev/null; then
      rm -f "$pidfile" 2>/dev/null || true
    fi
  fi

  # 2. If the systemd unit exists, that is the source of truth.
  if command -v systemctl >/dev/null 2>&1; then
    if systemd_unit_known "${svc}.service"; then
      if systemctl is-active --quiet "${svc}.service" 2>/dev/null; then
        return 0
      fi
      # Unit exists but isn't running. Try a quiet, non-interactive recover.
      if sudo -n systemctl start "${svc}.service" >/dev/null 2>&1; then
        info "Auto-healed: started inactive systemd watcher ${svc}.service."
      else
        warn "systemd watcher ${svc}.service is installed but not active."
        warn "Recover with: sudo systemctl start ${svc}.service"
      fi
      return 0
    fi
  fi

  # 3. Live detached watcher? Acceptable but not reboot-safe.
  if [[ -f "$pidfile" ]]; then
    return 0
  fi

  # 4. Nothing is running and nothing is installed. Warn once per invocation.
  if [[ "${VOX_WATCH_QUIET:-0}" == "1" ]]; then
    return 0
  fi
  warn "Autopull watcher is NOT running and no persistent service is installed."
  warn "Recover with: ./vox watch start    (installs systemd unit; survives reboot)"
  return 0
}

cmd_watch_repair() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  vox_init_dirs

  local svc
  svc=$(watch_service_name)

  info "Reconciling watcher state for ${svc}..."

  # Always reap stale pidfile first.
  local pidfile="$VOX_DIR/watch.pid"
  if [[ -f "$pidfile" ]]; then
    local existing_pid
    existing_pid=$(cat "$pidfile" 2>/dev/null || true)
    if [[ -z "$existing_pid" ]] || ! kill -0 "$existing_pid" 2>/dev/null; then
      rm -f "$pidfile"
      info "Cleared stale pidfile (PID ${existing_pid:-?} was dead)."
    fi
  fi

  # Prefer systemd path.
  if command -v systemctl >/dev/null 2>&1; then
    if systemd_unit_known "${svc}.service"; then
      if systemctl is-active --quiet "${svc}.service" 2>/dev/null; then
        info "systemd watcher ${svc}.service is already active. Nothing to do."
        return 0
      fi
      info "systemd unit exists but inactive — starting it."
      if ensure_sudo interactive && sudo_run 15 systemctl start "${svc}.service"; then
        info "Started ${svc}.service."
        return 0
      fi
      err "Could not start ${svc}.service. Try: sudo systemctl status ${svc}.service"
      return 1
    fi
    info "No systemd unit installed — installing now."
    cmd_watch_install_service
    return $?
  fi

  warn "systemctl not available — falling back to detached watcher."
  cmd_watch_start --detached
  return $?
}

cmd_watch_logs() {
  vox_maybe_load_config || true

  local follow=""
  while [[ $# -gt 0 ]]; do
    case "$1" in
      -f|--follow) follow="--follow"; shift ;;
      *) shift ;;
    esac
  done
  local logfile="$VOX_DIR/watch.log"
  if [[ ! -f "$logfile" ]]; then
    info "No watcher log at $logfile yet."
    return 0
  fi
  if [[ -n "$follow" ]]; then
    tail -n 200 -F "$logfile"
  else
    tail -n 200 "$logfile"
  fi
}

cmd_watch_once() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  vox_init_dirs
  watch_check_once
  return $?
}

cmd_watch_install_service() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  vox_init_dirs

  if ! command -v systemctl >/dev/null 2>&1; then
    err "systemctl not found. Install the watcher manually via './vox watch start'."
    return 1
  fi

  # Cache sudo credentials up-front; writing a unit file + daemon-reload needs
  # root. Interactive prompt here means the rest of this function can rely on
  # sudo_run succeeding without blocking.
  if ! ensure_sudo interactive; then
    err "Root access required to install systemd unit. Falling back: './vox watch start'"
    return 1
  fi

  local svc
  svc=$(watch_service_name)
  local unit_path="/etc/systemd/system/${svc}.service"
  local script_path
  script_path=$(vox_script_path)
  local run_user="${VOX_SERVICE_USER:-${SUDO_USER:-$USER}}"
  [[ -z "$run_user" ]] && run_user=$(id -un)
  local interval="${VOX_WATCH_INTERVAL:-15}"
  local logfile="$(cd "$WORK_DIR" && pwd)/$VOX_DIR/watch.log"
  local workdir="$(cd "$WORK_DIR" && pwd)"

  if [[ ! -x "$script_path" ]]; then
    err "vox script not executable at $script_path"
    return 1
  fi

  info "Installing systemd service $unit_path (user=$run_user, interval=${interval}s)"

  local tmp_unit
  tmp_unit=$(mktemp)
  cat > "$tmp_unit" <<UNIT
[Unit]
Description=vox autopull watcher for ${CFG_PROJECT_NAME:-$svc}
After=docker.service docker.socket network-online.target
Wants=network-online.target docker.socket
Requires=docker.service
# Never give up restarting — without these, systemd stops trying after 5
# restarts in 10s (the default StartLimit), which silently disables the
# watcher exactly when it is most needed (transient docker / network /
# git failures during boot).
StartLimitIntervalSec=0
StartLimitBurst=0

[Service]
Type=simple
User=${run_user}
WorkingDirectory=${workdir}
Environment=VOX_WATCH_INTERVAL=${interval}
Environment=HOME=$(getent passwd "$run_user" | cut -d: -f6 2>/dev/null || echo "/home/$run_user")
ExecStart=${script_path} watch start --foreground
# Restart on any exit (success, failure, signal, OOM, watchdog).
Restart=always
RestartSec=5
# Reap child processes (docker compose, git) cleanly on stop/restart.
KillMode=mixed
StandardOutput=append:${logfile}
StandardError=append:${logfile}
KillSignal=SIGTERM
TimeoutStopSec=15

[Install]
WantedBy=multi-user.target
UNIT

  if ! sudo_run 15 cp "$tmp_unit" "$unit_path"; then
    rm -f "$tmp_unit"
    err "Failed to write $unit_path — needs sudo. Re-run with sudo cached (sudo -v) or as root."
    return 1
  fi
  rm -f "$tmp_unit"
  sudo_run 15 chmod 0644 "$unit_path" >/dev/null 2>&1 || true

  local current_unit="${svc}.service"
  local old_svc seen_units=" "
  while IFS= read -r old_svc; do
    [[ -z "$old_svc" ]] && continue
    [[ "$seen_units" == *" $old_svc "* ]] && continue
    seen_units="${seen_units}${old_svc} "
    [[ "$old_svc" == "$current_unit" ]] && continue
    if systemd_unit_known "$old_svc"; then
      warn "Removing stale watcher service $old_svc"
      sudo_run 15 systemctl disable --now "$old_svc" >/dev/null 2>&1 || true
      sudo_run 15 rm -f "/etc/systemd/system/$old_svc" >/dev/null 2>&1 || true
    fi
  done < <(watch_service_candidates)

  if ! sudo_run 15 systemctl daemon-reload; then
    err "systemctl daemon-reload failed."
    return 1
  fi

  # Stop any foreground/local watcher so we don't double-deploy.
  cmd_watch_stop >/dev/null 2>&1 || true

  if ! sudo_run 15 systemctl enable "${svc}.service"; then
    err "systemctl enable ${svc}.service failed."
    return 1
  fi

  if ! sudo_run 30 systemctl restart "${svc}.service"; then
    err "systemctl restart ${svc}.service failed. Check: sudo journalctl -u ${svc}.service -n 80"
    return 1
  fi

  echo "${svc}.service" > "$VOX_DIR/watch.unit" 2>/dev/null || true
  info "Installed & started ${svc}.service (auto-starts on boot)."
  info "Logs:   ./vox watch logs --follow    (or: journalctl -u ${svc}.service -f)"
  info "Status: ./vox watch status"
}

cmd_watch_uninstall_service() {
  vox_maybe_load_config || true

  if ! command -v systemctl >/dev/null 2>&1; then
    info "systemctl not present — nothing to uninstall."
    return 0
  fi
  ensure_sudo interactive || {
    err "Root access required to remove systemd unit."
    return 1
  }
  local svc seen_units=" "
  while IFS= read -r svc; do
    [[ -z "$svc" ]] && continue
    [[ "$seen_units" == *" $svc "* ]] && continue
    seen_units="${seen_units}${svc} "
    local unit_path="/etc/systemd/system/${svc}"

    sudo_run 15 systemctl disable --now "$svc" >/dev/null 2>&1 || true
    if [[ -f "$unit_path" ]]; then
      if sudo_run 15 rm -f "$unit_path"; then
        info "Removed $unit_path."
      else
        warn "Could not remove $unit_path (needs sudo)."
      fi
    fi
  done < <(watch_service_candidates)
  rm -f "$VOX_DIR/watch.unit" 2>/dev/null || true
  sudo_run 15 systemctl daemon-reload >/dev/null 2>&1 || true
  info "Uninstalled watcher service."
}

cmd_watch_start() {
  local foreground=""
  local force_detached=""
  while [[ $# -gt 0 ]]; do
    case "$1" in
      -f|--foreground) foreground="1"; shift ;;
      --detached|--no-systemd) force_detached="1"; shift ;;
      *) shift ;;
    esac
  done

  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  vox_init_dirs

  local interval="${VOX_WATCH_INTERVAL:-15}"
  local pidfile="$VOX_DIR/watch.pid"
  local logfile="$VOX_DIR/watch.log"
  local svc
  svc=$(watch_service_name)

  # CRITICAL: --foreground must short-circuit BEFORE any "is the systemd
  # unit active?" check. systemd invokes us with --foreground, so we ARE
  # that unit — detecting ourselves and exiting 0 produces an infinite
  # restart loop that never deploys anything (the exact failure mode that
  # killed the watcher on this host until the bug was fixed).
  if [[ -n "$foreground" ]]; then
    echo "$$" > "$pidfile"
    trap 'rm -f "$pidfile"' EXIT
    watch_loop
    return $?
  fi

  # Guard against double-start (interactive paths only).
  if [[ -f "$pidfile" ]]; then
    local existing_pid
    existing_pid=$(cat "$pidfile" 2>/dev/null || true)
    if [[ -n "$existing_pid" ]] && kill -0 "$existing_pid" 2>/dev/null; then
      info "Watcher already running (PID $existing_pid). Use './vox watch stop' to stop it."
      return 0
    fi
    rm -f "$pidfile"
  fi

  # Also guard against the systemd-managed copy running, so we don't fork two
  # watchers fighting over the same repo (interactive paths only).
  if systemctl is-active --quiet "${svc}.service" 2>/dev/null; then
    info "systemd service ${svc}.service is active — nothing to do."
    info "To stop it:    sudo systemctl stop ${svc}.service   (or ./vox watch stop)"
    info "To uninstall:  ./vox watch uninstall-service"
    return 0
  fi

  # Default path: install/restart the systemd unit so the watcher survives
  # reboots, OOMs, and session teardown. A detached userspace fork is the
  # historical default but cannot satisfy the "always alive" guarantee — it
  # dies the moment the user logs out or the machine reboots. systemd's
  # Restart=always with no rate limit is the only mechanism that actually
  # self-heals. Detached fork remains a last-resort fallback.
  if [[ -z "$force_detached" ]] && command -v systemctl >/dev/null 2>&1; then
    if cmd_watch_install_service; then
      return 0
    fi
    warn "systemd install failed — falling back to detached watcher (will NOT survive reboot)."
    warn "Re-run with sudo cached (sudo -v) and './vox watch start' to retry persistent install."
  fi

  info "Starting autopull watcher (interval: ${interval}s)"
  info "Deploys on origin-ahead OR local-vs-deployed drift."
  info "Log:    $logfile"
  info "Stop:   ./vox watch stop"
  info "Persist across reboots: ./vox watch install-service"

  # Fully detach: setsid creates a new session so SIGHUP from the parent shell
  # does not reach the loop. nohup is a belt-and-braces fallback when setsid
  # is unavailable (BSD-ish environments).
  local launcher=""
  if command -v setsid >/dev/null 2>&1; then
    launcher="setsid"
  elif command -v nohup >/dev/null 2>&1; then
    launcher="nohup"
  fi

  local script_path
  script_path=$(vox_script_path)

  if [[ -n "$launcher" ]]; then
    $launcher bash -c "cd '$WORK_DIR' && exec '$script_path' watch start --foreground" \
      </dev/null >>"$logfile" 2>&1 &
  else
    # Last-resort path: bare subshell with disown.
    (
      cd "$WORK_DIR"
      exec "$script_path" watch start --foreground
    ) </dev/null >>"$logfile" 2>&1 &
    disown
  fi
  local launched_pid=$!

  # Give the child a beat to write its own pidfile.
  local i
  for i in 1 2 3 4 5 6 7 8 9 10; do
    if [[ -f "$pidfile" ]]; then break; fi
    sleep 0.2
  done

  if [[ -f "$pidfile" ]]; then
    info "Watcher started (PID $(cat "$pidfile"))."
  else
    info "Watcher launched (PID $launched_pid) — check $logfile if nothing happens."
  fi
}

cmd_watch() {
  local subcmd="${1:-start}"
  case "$subcmd" in
    start|stop|status|once|logs|install-service|uninstall-service|repair)
      shift 2>/dev/null || true
      ;;
    -f|--foreground)
      subcmd="start"
      # keep flag for cmd_watch_start to see
      ;;
    *)
      err "Unknown watch subcommand: $subcmd"
      echo "Available: start | stop | status | once | logs | repair | install-service | uninstall-service"
      return 1
      ;;
  esac

  case "$subcmd" in
    start)             cmd_watch_start "$@" ;;
    stop)              cmd_watch_stop "$@" ;;
    status)            cmd_watch_status "$@" ;;
    once)              cmd_watch_once "$@" ;;
    logs)              cmd_watch_logs "$@" ;;
    repair)            cmd_watch_repair "$@" ;;
    install-service)   cmd_watch_install_service "$@" ;;
    uninstall-service) cmd_watch_uninstall_service "$@" ;;
  esac
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: destroy
# ═════════════════════════════════════════════════════════════════════════════

cmd_destroy() {
  vox_load_config
  WORK_DIR="$(pwd)"
  REPO_PATH="$WORK_DIR/$CFG_REPO_DIR"
  COMPOSE_CMD="${CFG_COMPOSE_CMD:-docker compose}"

  echo ""
  warn "This will stop and remove ALL vox-generated files from this directory."
  warn "Project: $CFG_PROJECT_NAME  |  Repo: $REPO_PATH"
  echo ""

  if ! confirm "Are you SURE you want to destroy everything?"; then
    info "Aborted."
    return 0
  fi

  # Kill watcher if running
  local pidfile="$VOX_DIR/watch.pid"
  if [[ -f "$pidfile" ]]; then
    local wpid
    wpid=$(cat "$pidfile")
    kill "$wpid" 2>/dev/null || true
    rm -f "$pidfile"
    info "Stopped autopull watcher."
  fi

  cd "$WORK_DIR"

  # 1. Stop and remove containers, volumes, images
  info "Taking down containers, volumes, and local images..."
  $COMPOSE_CMD down --volumes --rmi local 2>/dev/null || true

  # 2. Remove generated files inside the repo
  if [[ -d "$REPO_PATH" ]]; then
    info "Removing generated files from $CFG_REPO_DIR/..."
    rm -f "$REPO_PATH/Dockerfile"
    rm -f "$REPO_PATH/entrypoint.sh"
    rm -f "$REPO_PATH/.dockerignore"
    rm -f "$REPO_PATH/.env"
  fi

  # 3. Remove docker-compose.yml from working dir
  rm -f "$WORK_DIR/docker-compose.yml"

  # 4. Remove .cloudflared/ if present
  rm -rf "$WORK_DIR/.cloudflared"

  # 5. Remove .vox/ state
  info "Removing .vox/ state..."
  rm -rf "$VOX_DIR"

  # 6. Remove the cloned repo
  if [[ -d "$REPO_PATH" ]]; then
    rm -rf "$REPO_PATH"
    info "Removed $REPO_PATH"
  fi

  info "Destroy complete. Directory is clean."
}

# ═════════════════════════════════════════════════════════════════════════════
# SUBCOMMAND: help
# ═════════════════════════════════════════════════════════════════════════════

cmd_help() {
  banner "vox — Deploy Any Repo"
  box_line "Usage: ./vox <command> [options]"
  box_line ""
  box_line "One-liner deploy (no prompts):"
  box_line "  ./vox setup --repo URL --token TOKEN --hostname DOMAIN"
  box_line "  ./vox setup --repo URL --token TOKEN --hostname DOMAIN --env .env"
  box_line "  ./vox setup --repo URL --token TOKEN --hostname DOMAIN --branch dev"
  box_line ""
  box_line "Commands:"
  box_line "  setup               Interactive first-time setup"
  box_line "  deploy              Pull latest + rebuild + zero-downtime restart"
  box_line "  logs [--follow]     Show container logs"
  box_line "  status              Show container health, uptime, current SHA"
  box_line "  stop                Stop all services"
  box_line "  start               Start services"
  box_line "  restart             Restart services"
  box_line "  rollback [n]        Roll back n deploys (default: 1)"
  box_line "  env                 Show env vars (secrets masked)"
  box_line "  env set KEY=VALUE   Add/update an env var and redeploy"
  box_line "  env unset KEY       Remove an env var and redeploy"
  box_line "  history             Show last 20 deploys"
  box_line "  watch                       Start autopull watcher (on by default after setup)"
  box_line "  watch stop|status|logs      Manage the running watcher"
  box_line "  watch once                  Run one fetch + deploy-if-needed (cron/webhook)"
  box_line "  watch install-service       Install systemd unit so watcher survives reboots"
  box_line "  watch uninstall-service     Remove the systemd unit"
  box_line "  destroy             Tear down everything (confirms first)"
  box_line "  help                Show this message"
  box_line ""
  box_line "Setup flags:"
  box_line "  --repo URL          Git repo URL"
  box_line "  --token TOKEN       Cloudflare Tunnel token"
  box_line "  --hostname DOMAIN   Public hostname (e.g. app.example.com)"
  box_line "  --domain DOMAIN     Alias for --hostname"
  box_line "  --env PATH          Path to .env file"
  box_line "  --branch BRANCH     Git branch (default: main)"
  box_line "  --autopull false    Disable auto-redeploy watcher"
  box_line "  --auto-install true Enable auto-install on lockfile change"
  box_line "  --skip-gpu          Skip NVIDIA Container Toolkit configuration"
  box_render
}

# ═════════════════════════════════════════════════════════════════════════════
# COMMAND DISPATCHER
# ═════════════════════════════════════════════════════════════════════════════

# Determine subcommand: first arg that does not look like a file path
SUBCOMMAND="${1:-}"
shift 2>/dev/null || true

# Commands that need a live docker daemon. `help`, `history`, `env` (read),
# and `watch stop/status` are intentionally excluded — they should work even
# when docker is down so the user can diagnose the situation.
case "$SUBCOMMAND" in
  setup|deploy|logs|status|stop|start|restart|rollback|destroy)
    require_docker
    ;;
  env)
    # `env set` / `env unset` redeploy the container, so they need docker.
    # Plain `env` (read-only display) does not.
    case "${1:-}" in
      set|unset) require_docker ;;
    esac
    ;;
  watch)
    # Only branches that actually invoke docker need the gate. `once` still
    # triggers a deploy, so it needs docker too.
    case "${1:-start}" in
      start|once|install-service) require_docker ;;
    esac
    ;;
esac

# Self-heal the autopull watcher on any command that implies the service
# should be running. Cheap and silent when state is correct; warns or auto-
# starts the systemd unit when it isn't. Excluded: setup (manages the watcher
# itself), stop, destroy, uninstall, watch (handles its own state), help,
# history (read-only).
case "$SUBCOMMAND" in
  deploy|status|start|restart|rollback|logs|env)
    watch_ensure_alive || true
    ;;
esac

case "$SUBCOMMAND" in
  setup)
    cmd_setup "$@"
    ;;
  deploy)
    cmd_deploy "$@"
    ;;
  logs)
    cmd_logs "$@"
    ;;
  status)
    cmd_status "$@"
    ;;
  stop)
    cmd_stop "$@"
    ;;
  start)
    cmd_start "$@"
    ;;
  restart)
    cmd_restart "$@"
    ;;
  rollback)
    cmd_rollback "$@"
    ;;
  env)
    cmd_env "$@"
    ;;
  history)
    cmd_history "$@"
    ;;
  watch)
    cmd_watch "$@"
    ;;
  destroy)
    cmd_destroy "$@"
    ;;
  help|--help|-h)
    cmd_help
    ;;
  "")
    cmd_help
    ;;
  *)
    err "Unknown command: $SUBCOMMAND"
    echo ""
    cmd_help
    exit 1
    ;;
esac