#!/bin/bash
#
# sbo-batch-test - batch-test SlackBuilds against a clean Slackware 15.0
# overlay chroot. Non-interactive, dependency-resolving, per-target disposable
# overlay, persistent logs, color summary.
#
# Some parts of this script are inspired by overlay-chroot.sh by Slackware user
# bassmadrigal (Jeremy Hansen): specifically the overlayfs setup, the system
# bind mounts (dev, proc, sys, dev/pts, resolv.conf, dbus machine-id), the base
# patching from the local mirror, and the teardown ordering. That teardown order
# (pts, dev/proc/sys, resolv.conf, dbus machine-id, overlay last) is preserved
# deliberately, it is the correct unwind order.
#
# Runs INSIDE a Slackware64-current VM. Verifies SlackBuilds BUILD and install
# cleanly against 15.0 userland. Does NOT test kernel modules (shares host
# kernel). Resolution is LOCAL-tree-only, never network. Does not touch
# slackrepo.
#
# No em dashes in prose by author convention.

# =============================================================================
# CONFIG
# =============================================================================
#
# Do NOT edit values here. Real config lives in an external file, sourced below.
# Default path: ~/.config/sbo-batch-tester/config (override with $SBO_BATCH_CONFIG).
# Copy config.example from the repo and edit it. Runs as root, so ~ is root's
# home (/root/.config/sbo-batch-tester/config).
#
# Config file sets these (see config.example for docs on each):
#   SLACKWARE_BASE LOCAL_MIRROR_15 SBO_TREE_ROOTS CHROOT_LOCATION LOG_ROOT VERSION

# Defaults. The config file overrides any it sets. These are placeholders, a run
# fails fast in validate_env / init_base if the config has not set real paths.
SLACKWARE_BASE=""
LOCAL_MIRROR_15=""
SBO_TREE_ROOTS=()
CHROOT_LOCATION="/tmp"
LOG_ROOT="/var/log/sbo-batch-test"

# Persistent package cache (local disk). Built dependency packages are stored
# here and reused across runs while their version is unchanged. Empty disables
# the cache (every package builds fresh). Wiped automatically when the base is
# patched. Layout mirrors the SBo tree: <cat>/<prog>/<prog>-<ver>-...txz
PKG_CACHE=""

VERSION="15.0"

# Source the external config if present. Not an error here if missing (keeps the
# script sourceable by test-logic.sh); validate_env / init_base report it.
SBO_BATCH_CONFIG="${SBO_BATCH_CONFIG:-$HOME/.config/sbo-batch-tester/config}"
if [[ -f "$SBO_BATCH_CONFIG" ]]; then
  # shellcheck disable=SC1090
  source "$SBO_BATCH_CONFIG"
fi

# Derived: the actual Slackware tree under the mirror mountpoint. Holds
# ChangeLog.txt, slackware64/, and patches/. Set after sourcing so it picks up
# the config's LOCAL_MIRROR_15 and VERSION.
MIRROR_TREE="$LOCAL_MIRROR_15/slackware64-$VERSION"

# =============================================================================
# END CONFIG
# =============================================================================

set -uo pipefail
# Note: NOT using -e globally. One package build failing is an expected,
# handled outcome, not a script crash. Per-package execution is isolated.

# ---- flags / globals --------------------------------------------------------
USE_COLOR=1     # --no-color or non-TTY disables
DRY_RUN=0       # resolve + print build order, do not build
WITH_X=0        # --with-x: optional X passthrough (default headless)
JOBS=1          # -j: reserved, see TODO
INIT_BASE=0     # --init-base: populate SLACKWARE_BASE from the mirror, then exit
TARGET_ARG=""

RUN_DIR=""              # timestamped log dir for this run
declare -a ACTIVE_MOUNTS=()   # overlay chroot roots currently mounted (for trap unwind)
CURRENT_OVERLAY=""            # the $TMPDIR of the overlay being built in now

# Status tracking. Keyed by "category/prog". Parallel assoc arrays.
declare -A ST_STATUS=()   # SUCCESS|BUILD-FAILED|DOWNLOAD-FAILED|MD5-MISMATCH|INSTALL-FAILED|BLOCKED-BY-DEP|UNMET-DEP
declare -A ST_REASON=()
declare -A ST_TIME=()     # elapsed seconds
declare -A ST_README=()   # 1 if package carries %README%

# =============================================================================
# usage
# =============================================================================
usage() {
  cat <<'EOF'
sbo-batch-test - batch-test SlackBuilds against a clean Slackware 15.0 overlay chroot

USAGE:
  sbo-batch-test [OPTIONS] <program-name>
  sbo-batch-test [OPTIONS] <category-folder>

MODES:
  <program-name>     Resolve its full SBo dependency tree, build+install every
                     dep in topological order, then build+install the target.
  <category-folder>  Treat every SlackBuild dir inside as an independent target.
                     Each target gets its OWN fresh overlay against pristine 15.0.

OPTIONS:
  -h, --help       This text.
  --no-color       Disable ANSI color (auto-disabled when stdout is not a TTY).
  --dry-run        Resolve and print the build order, do not build.
  --with-x         Enable X passthrough via xhost +local:hosts (security caveat:
                   allows local non-network connections to your X server).
                   Default is headless (no X).
  -j, --jobs N     Reserved. Currently a no-op stub (builds are serial).
  --init-base      First-time populate SLACKWARE_BASE with the FULL 15.0
                   package set from the mirror, then exit. Run once before the
                   first build. Refuses to clobber an existing base.

EXTENSION POINTS (not implemented, see TODOs in source):
  - "all" mode (build every package across all SBo roots).
  - queue/list-file mode (build a named list of targets).
  - -j parallelism.

EOF
}

# =============================================================================
# color helpers
# =============================================================================
init_color() {
  if [[ $USE_COLOR -eq 1 && -t 1 ]]; then
    C_RED=$'\e[31m'; C_GRN=$'\e[32m'; C_YEL=$'\e[33m'; C_RST=$'\e[0m'
  else
    C_RED=""; C_GRN=""; C_YEL=""; C_RST=""
  fi
}

# =============================================================================
# arg parsing
# =============================================================================
parse_args() {
  while [[ $# -gt 0 ]]; do
    case "$1" in
      -h|--help) usage; exit 0 ;;
      --no-color) USE_COLOR=0; shift ;;
      --dry-run) DRY_RUN=1; shift ;;
      --with-x) WITH_X=1; shift ;;
      -j|--jobs) JOBS="${2:-1}"; shift 2 ;;  # TODO: implement parallelism
      --init-base) INIT_BASE=1; shift ;;
      -*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
      *)
        if [[ -n "$TARGET_ARG" ]]; then
          echo "Only one target argument accepted (got '$TARGET_ARG' and '$1')." >&2
          exit 2
        fi
        TARGET_ARG="$1"; shift ;;
    esac
  done
  if [[ -z "$TARGET_ARG" && $INIT_BASE -eq 0 ]]; then
    echo "No target given." >&2; usage >&2; exit 2
  fi
}

# =============================================================================
# startup validation (fail fast, copy-pasteable hints)
# =============================================================================

# Shared: the config file must exist and set the required paths. Called by both
# validate_env and init_base.
require_config() {
  if [[ ! -f "$SBO_BATCH_CONFIG" ]]; then
    cat >&2 <<EOF
No config file: $SBO_BATCH_CONFIG
Copy the example and edit it (paths run as root, so this is /root/.config/...):

  mkdir -p "\$(dirname "$SBO_BATCH_CONFIG")"
  cp config.example "$SBO_BATCH_CONFIG"
  \${EDITOR:-vi} "$SBO_BATCH_CONFIG"
EOF
    exit 1
  fi
  if [[ -z "$SLACKWARE_BASE" || -z "$LOCAL_MIRROR_15" || ${#SBO_TREE_ROOTS[@]} -eq 0 ]]; then
    echo "Config $SBO_BATCH_CONFIG is missing SLACKWARE_BASE, LOCAL_MIRROR_15, or SBO_TREE_ROOTS." >&2
    exit 1
  fi
}

validate_env() {
  if [[ $EUID -ne 0 ]]; then
    echo "This tool must run as root (overlay + chroot)." >&2
    exit 1
  fi
  require_config

  # SLACKWARE_BASE: local, looks like a real Slackware install.
  if [[ ! -d "$SLACKWARE_BASE" || ! -d "$SLACKWARE_BASE/var/log/packages" ]]; then
    cat >&2 <<EOF
SLACKWARE_BASE is missing or incomplete: $SLACKWARE_BASE
It must be a LOCAL (non-NFS) full Slackware 15.0 install tree.
Populate it from the mirror with the FULL package set (not minimal,
a minimal base causes false "missing dependency" results):

  $0 --init-base
EOF
    exit 1
  fi
  # Guard against the classic mistake: base sitting on the NFS mirror path.
  case "$SLACKWARE_BASE" in
    "$LOCAL_MIRROR_15"*)
      echo "SLACKWARE_BASE must NOT live under LOCAL_MIRROR_15 (NFS). overlayfs over NFS lowerdir is unsupported here." >&2
      exit 1 ;;
  esac

  # LOCAL_MIRROR_15: NFS, fstab entry is noauto. Auto-mount if not mounted
  # (needs the fstab entry for bare `mount <path>`). Left mounted after the run.
  if ! mountpoint -q "$LOCAL_MIRROR_15"; then
    echo "LOCAL_MIRROR_15 not mounted, attempting: mount $LOCAL_MIRROR_15" >&2
    if ! mount "$LOCAL_MIRROR_15"; then
      echo "Could not mount $LOCAL_MIRROR_15 (no fstab entry? mount it manually)." >&2
      exit 1
    fi
  fi
  if [[ ! -f "$MIRROR_TREE/ChangeLog.txt" ]]; then
    echo "Mirror mounted but no ChangeLog.txt under: $MIRROR_TREE" >&2
    echo "Expected the Slackware 15.0 tree at \$LOCAL_MIRROR_15/slackware64-\$VERSION." >&2
    exit 1
  fi

  # SBo roots exist locally.
  local r found=0
  for r in "${SBO_TREE_ROOTS[@]}"; do
    if [[ -d "$r" ]]; then found=1; else
      echo "SBO_TREE_ROOTS path does not exist: $r" >&2
    fi
  done
  if [[ $found -eq 0 ]]; then
    echo "No valid SBo tree root found. Fix SBO_TREE_ROOTS." >&2
    exit 1
  fi
}

# =============================================================================
# keep base patched from the mirror (reuse reference logic, point at NFS mirror,
# write to local base). Skipped on --dry-run.
# =============================================================================
# =============================================================================
# first-time base populate. --init-base only. Installs the FULL 15.0 package
# set from the mirror into SLACKWARE_BASE, then exits (caller does not build).
# Refuses to clobber an already-populated base.
# =============================================================================
init_base() {
  if [[ $EUID -ne 0 ]]; then
    echo "--init-base must run as root (installpkg --root)." >&2; exit 1
  fi
  require_config
  case "$SLACKWARE_BASE" in
    "$LOCAL_MIRROR_15"*)
      echo "SLACKWARE_BASE must NOT live under LOCAL_MIRROR_15 (NFS)." >&2; exit 1 ;;
  esac
  if ! mountpoint -q "$LOCAL_MIRROR_15"; then
    echo "LOCAL_MIRROR_15 not mounted, attempting: mount $LOCAL_MIRROR_15" >&2
    if ! mount "$LOCAL_MIRROR_15"; then
      echo "Could not mount $LOCAL_MIRROR_15 (no fstab entry? mount it manually)." >&2; exit 1
    fi
  fi
  if [[ ! -f "$MIRROR_TREE/ChangeLog.txt" ]]; then
    echo "Mirror mounted but no ChangeLog.txt under: $MIRROR_TREE" >&2; exit 1
  fi
  if [[ -d "$SLACKWARE_BASE/var/log/packages" ]]; then
    echo "Base already populated: $SLACKWARE_BASE" >&2
    echo "Remove it first to re-init, or just run a build (update_base keeps it patched)." >&2
    exit 1
  fi
  echo "Populating base from mirror into: $SLACKWARE_BASE"
  mkdir -p "$SLACKWARE_BASE"
  local p n=0
  for p in "$MIRROR_TREE"/slackware64/*/*.t?z; do
    [[ -e "$p" ]] || continue
    installpkg --terse --root "$SLACKWARE_BASE" "$p"
    ((n++)); ((n % 50 == 0)) && echo "  ...$n packages"
  done
  if [[ $n -eq 0 ]]; then
    echo "No packages found under $MIRROR_TREE/slackware64/*/. Wrong mirror layout?" >&2
    exit 1
  fi
  # Seed the update marker so the next run does not re-patch needlessly.
  head -n1 "$MIRROR_TREE/ChangeLog.txt" > "$SLACKWARE_BASE/last-base-update"
  echo "Base populated: $n packages installed into $SLACKWARE_BASE"
}

update_base() {
  local marker="$SLACKWARE_BASE/last-base-update"
  touch "$marker"
  local head_now; head_now="$(head -n1 "$MIRROR_TREE/ChangeLog.txt")"
  if [[ "$head_now" == "$(cat "$marker")" ]]; then
    echo "Base is up-to-date with the mirror."
    return
  fi
  echo "Patching base from mirror..."
  local p
  for p in "$MIRROR_TREE"/patches/packages/*.t?z; do
    [[ -e "$p" ]] || continue
    if [[ ! -e "$SLACKWARE_BASE/var/lib/pkgtools/packages/$(basename "${p%.*}")" ]]; then
      ROOT="$SLACKWARE_BASE" upgradepkg --terse --install-new "$p"
    fi
  done
  echo "$head_now" > "$marker"
  echo "Base patched."
}

# =============================================================================
# Package cache. Persistent, on-disk store of built packages so unchanged deps
# are installed from cache instead of rebuilt. Layout mirrors the SBo tree:
#   $PKG_CACHE/<cat>/<prog>/<prog>-<ver>-<arch>-<build>_<tag>.txz
# One .txz per prog dir (the latest tested build). Key is prog+version; build
# number, arch, and tag do not affect a hit. Empty PKG_CACHE disables caching.
# =============================================================================

# Echo the version field of a cached package filename. <file> is a basename like
# prog-1.2-x86_64-1_danix.txz; prog may itself contain dashes, so strip the known
# prog prefix first, then take the field up to the next dash.
_cache_ver_of() {
  local prog="$1" base="$2"
  base="${base#"$prog"-}"     # drop "prog-"
  echo "${base%%-*}"          # version is up to the next dash
}

# cache_decision <cat> <prog> <version> -> echoes: cached | bump:OLD:NEW | new
cache_decision() {
  local cat="$1" prog="$2" version="$3"
  [[ -z "$PKG_CACHE" ]] && { echo new; return; }
  local dir="$PKG_CACHE/$cat/$prog"
  local f newest=""
  for f in "$dir/$prog"-*.t?z; do
    [[ -e "$f" ]] || continue
    [[ -z "$newest" || "$f" -nt "$newest" ]] && newest="$f"
  done
  [[ -z "$newest" ]] && { echo new; return; }
  local have; have="$(_cache_ver_of "$prog" "$(basename "$newest")")"
  if [[ "$have" == "$version" ]]; then
    echo cached
  else
    echo "bump:$have:$version"
  fi
}

# cache_path <cat> <prog> <version> -> echoes the cached .txz path for that
# version, or nothing. Used to installpkg a cached dep.
cache_path() {
  local cat="$1" prog="$2" version="$3"
  [[ -z "$PKG_CACHE" ]] && return
  local dir="$PKG_CACHE/$cat/$prog"
  local f newest=""
  for f in "$dir/$prog"-*.t?z; do
    [[ -e "$f" ]] || continue
    [[ -z "$newest" || "$f" -nt "$newest" ]] && newest="$f"
  done
  [[ -z "$newest" ]] && return
  [[ "$(_cache_ver_of "$prog" "$(basename "$newest")")" == "$version" ]] && echo "$newest"
}

# cache_store <cat> <prog> <src-txz> -> clear the prog dir, copy src in.
cache_store() {
  local cat="$1" prog="$2" src="$3"
  [[ -z "$PKG_CACHE" ]] && return
  local dir="$PKG_CACHE/$cat/$prog"
  mkdir -p "$dir"
  rm -f "$dir"/*.t?z
  cp -a "$src" "$dir/"
}

# =============================================================================
# SBo tree lookup. Find the SlackBuild dir for a prog name across roots.
# Echoes the dir path, returns 0 if found, 1 otherwise.
# =============================================================================
find_slackbuild_dir() {
  local prog="$1" root d
  for root in "${SBO_TREE_ROOTS[@]}"; do
    [[ -d "$root" ]] || continue
    # <root>/<category>/<prog>
    for d in "$root"/*/"$prog"; do
      if [[ -d "$d" && -f "$d/$prog.info" ]]; then
        echo "$d"; return 0
      fi
    done
  done
  return 1
}

# Category of a SlackBuild dir = its parent dir name.
category_of() { basename "$(dirname "$1")"; }
# Key used in status maps and log filenames.
pkg_key() { echo "$(category_of "$1")/$(basename "$1")"; }

# Read REQUIRES from a .info, stripped. Echoes space-separated tokens.
read_requires() {
  local info="$1"
  # shellcheck disable=SC1090
  ( set +u; source "$info"; echo "${REQUIRES:-}" )
}

# Echo the VERSION field from a SlackBuild dir's .info (empty if unreadable).
# Used as the cache key's version component.
version_of() {
  local dir="$1"
  local info="$dir/$(basename "$dir").info"
  [[ -f "$info" ]] || return
  # .info lines look like: VERSION="1.2.3"
  local v; v="$(grep -m1 '^VERSION=' "$info" | cut -d'"' -f2)"
  echo "$v"
}

# =============================================================================
# DEPENDENCY RESOLUTION
# Builds a topological order over the local SBo tree.
#  - transitive REQUIRES
#  - %README% recorded, not built
#  - deps already in base (installed in chroot base) are satisfied, not built
#  - deps neither in SBo tree nor installed => UNMET-DEP
#  - cycles detected and reported, no infinite loop
#
# Outputs the order into the global array RESOLVED_ORDER (dir paths).
# Records unmet deps into UNMET (prog -> requiring pkg) and cycle errors.
# Returns 1 if any hard resolution failure (unmet dep, cycle) for the target set.
# =============================================================================
declare -a RESOLVED_ORDER=()
declare -A UNMET=()         # prog -> "needed by X"
declare -a CYCLES=()        # human-readable cycle descriptions
declare -A HAS_README=()    # dir -> 1 if its REQUIRES carried %README%

# Is a prog already installed in the base tree? (stock 15.0 or otherwise present)
installed_in_base() {
  local prog="$1"
  # Package db entries look like prog-version-arch-build[ tag]
  ls "$SLACKWARE_BASE"/var/log/packages/ 2>/dev/null \
    | grep -qE "^${prog}-[^-]+-[^-]+-[^-]+"
}

# DFS topo sort with cycle detection.
# visit_state: dir -> 0 visiting (on stack), 1 done
declare -A _vstate=()
_resolve_visit() {
  local dir="$1" parent="$2"
  local key; key="$(basename "$dir")"

  if [[ "${_vstate[$dir]:-}" == "1" ]]; then return 0; fi
  if [[ "${_vstate[$dir]:-}" == "0" ]]; then
    CYCLES+=("cycle involving $key (pulled in via $parent)")
    return 1
  fi
  _vstate["$dir"]=0

  local info="$dir/$(basename "$dir").info"
  local req tok depdir rc=0
  req="$(read_requires "$info")"
  for tok in $req; do
    if [[ "$tok" == "%README%" ]]; then
      HAS_README["$dir"]=1
      continue
    fi
    if depdir="$(find_slackbuild_dir "$tok")"; then
      _resolve_visit "$depdir" "$key" || rc=1
    elif installed_in_base "$tok"; then
      : # satisfied by base, nothing to build
    else
      UNMET["$tok"]="needed by $key"
      rc=1
    fi
  done

  _vstate["$dir"]=1
  RESOLVED_ORDER+=("$dir")
  return $rc
}

# Resolve a single target dir into RESOLVED_ORDER (deps first, target last).
resolve_target() {
  local dir="$1"
  RESOLVED_ORDER=()
  CYCLES=()
  UNMET=()
  _vstate=()
  _resolve_visit "$dir" "(top)"
}

# =============================================================================
# OVERLAY LIFECYCLE (per target). Patterns from overlay-chroot.sh.
# setup_overlay -> echoes the chroot root path, sets CURRENT_OVERLAY.
# teardown_overlay <tmpdir> -> idempotent unwind in correct reverse order.
# =============================================================================
setup_overlay() {
  local tmpdir; tmpdir="$(mktemp -d "$CHROOT_LOCATION"/sbo-bt.XXXXXX)"
  mkdir "$tmpdir"/{changes,tmp,chroot}

  # overlayfs: read-only 15.0 base as lowerdir, disposable upper on top.
  mount -t overlay overlay \
    -olowerdir="$SLACKWARE_BASE",upperdir="$tmpdir/changes",workdir="$tmpdir/tmp" \
    "$tmpdir/chroot"

  # bind system dirs
  mkdir -p "$tmpdir"/changes/{dev,proc,sys}
  local i
  for i in dev proc sys; do
    mount -o bind "/$i" "$tmpdir/chroot/$i"
  done
  # /dev/pts (sudo/pty)
  mkdir -p "$tmpdir"/changes/dev/pts
  mount -o bind /dev/pts "$tmpdir/chroot/dev/pts"
  # internet
  mount -o bind /etc/resolv.conf "$tmpdir/chroot/etc/resolv.conf"
  chroot "$tmpdir/chroot" /bin/bash -c "/usr/sbin/update-ca-certificates --fresh >/dev/null 2>&1" || true
  # dbus machine-id
  touch "$tmpdir/chroot/var/lib/dbus/machine-id"
  mount -o bind /var/lib/dbus/machine-id "$tmpdir/chroot/var/lib/dbus/machine-id"

  CURRENT_OVERLAY="$tmpdir"
  ACTIVE_MOUNTS+=("$tmpdir")
  echo "$tmpdir"
}

# Idempotent teardown. Safe to call twice, safe mid-abort.
teardown_overlay() {
  local tmpdir="$1"
  [[ -n "$tmpdir" && -d "$tmpdir" ]] || return 0
  local c="$tmpdir/chroot"

  mountpoint -q "$c/dev/pts" && umount "$c/dev/pts"
  local i
  for i in dev proc sys; do
    mountpoint -q "$c/$i" && umount "$c/$i"
  done
  mountpoint -q "$c/etc/resolv.conf" && umount "$c/etc/resolv.conf"
  mountpoint -q "$c/var/lib/dbus/machine-id" && umount "$c/var/lib/dbus/machine-id"
  mountpoint -q "$c" && umount "$c"

  # Remove from ACTIVE_MOUNTS
  local n=() m
  for m in "${ACTIVE_MOUNTS[@]}"; do [[ "$m" != "$tmpdir" ]] && n+=("$m"); done
  ACTIVE_MOUNTS=("${n[@]:-}")

  rm -rf "$tmpdir"
}

# Trap: unwind every live overlay on abort. Reverse order of creation.
cleanup_trap() {
  [[ $WITH_X -eq 1 ]] && xhost -local:hosts >/dev/null 2>&1 || true
  local i
  for (( i=${#ACTIVE_MOUNTS[@]}-1; i>=0; i-- )); do
    teardown_overlay "${ACTIVE_MOUNTS[$i]}"
  done
}
trap cleanup_trap EXIT INT TERM

# =============================================================================
# BUILD + INSTALL one package inside an existing overlay chroot.
# Args: <chroot-tmpdir> <slackbuild-dir>
# Sets ST_STATUS / ST_REASON / ST_TIME for the package key.
# Returns 0 on SUCCESS, 1 otherwise.
# =============================================================================
build_one() {
  local tmpdir="$1" dir="$2" is_target="${3:-0}"
  local c="$tmpdir/chroot"
  local prog cat key
  prog="$(basename "$dir")"; cat="$(category_of "$dir")"; key="$cat/$prog"
  local logf="$RUN_DIR/${cat}_${prog}.log"
  local start; start=$(date +%s)
  local version; version="$(version_of "$dir")"

  # %README% reminder carries through to summary
  [[ "${HAS_README[$dir]:-}" == "1" ]] && ST_README["$key"]=1

  # Dependency with a version-matching cached package: installpkg it into the
  # overlay and skip the build entirely. The target never takes this path.
  if [[ "$is_target" != "1" ]]; then
    local cached; cached="$(cache_path "$cat" "$prog" "$version")"
    if [[ -n "$cached" ]]; then
      local cb; cb="$(basename "$cached")"
      local workroot="/sbo-work"
      mkdir -p "$c$workroot"
      cp -a "$cached" "$c$workroot/"
      {
        echo "===== sbo-batch-test: $prog (from cache) ====="
        echo "cached package: $cb"
      } >> "$logf"
      if chroot "$c" /bin/bash -c "installpkg --terse '$workroot/$cb'" >>"$logf" 2>&1; then
        ST_TIME["$key"]=$(( $(date +%s) - start ))
        ST_STATUS["$key"]="CACHED"
        return 0
      fi
      # Cache install failed: fall through and build fresh.
      # installpkg is not atomic; a partial cache install is fine here because the
      # overlay is disposable per target. Rebuild fresh below.
      echo "cache install failed, building fresh" >> "$logf"
    fi
  fi

  # 1. copy SlackBuild dir into the overlay
  local workroot="/sbo-work"
  mkdir -p "$c$workroot"
  cp -a "$dir" "$c$workroot/$prog"

  # 2-5. download, md5, build, install all run INSIDE the chroot non-interactively.
  # The heredoc script writes a status token to a known file we read back out.
  # overlayfs note: if a build fails ONLY here and works on bare 15.0, suspect
  # an overlayfs sharp edge (rename/whiteout quirks) rather than a real build bug.
  local statf="$c$workroot/$prog.status"
  chroot "$c" /bin/bash -s <<CHROOT_EOF >>"$logf" 2>&1
set -uo pipefail
cd "$workroot/$prog" || { echo "BUILD-FAILED: cannot cd"; echo BUILD-FAILED > "$workroot/$prog.status"; exit 1; }
. ./$prog.info

# Force a controlled output dir so the harness, not the SlackBuild's environment,
# decides where the package lands. Never inherit OUTPUT (the user's -current repo
# convention sets it to /repo, which must not be touched here).
export OUTPUT=/sbo-work/output
mkdir -p "\$OUTPUT"

# Log resolved build context so the overlay never needs to be kept.
echo "===== sbo-batch-test: $prog ====="
echo "PRGNAM=\${PRGNAM:-$prog} VERSION=\${VERSION:-?} BUILD=\${BUILD:-?} TAG=\${TAG:-?}"
echo "uname -m: \$(uname -m)   OUTPUT=\$OUTPUT"
echo "REQUIRES=\${REQUIRES:-}"
echo "================================="

# pick arch-specific download/md5 if present (x86_64 VM)
if [ "\$(uname -m)" = "x86_64" ] && [ -n "\${DOWNLOAD_x86_64:-}" ] && [ "\${DOWNLOAD_x86_64}" != "UNSUPPORTED" ] && [ "\${DOWNLOAD_x86_64}" != "UNTESTED" ]; then
  DL="\$DOWNLOAD_x86_64"; MD="\$MD5SUM_x86_64"
else
  DL="\$DOWNLOAD"; MD="\$MD5SUM"
fi

# 2. download
for u in \$DL; do
  wget -c --tries=3 "\$u" || { echo DOWNLOAD-FAILED > "$workroot/$prog.status"; exit 1; }
done

# 3. verify md5
set -- \$MD
for u in \$DL; do
  f="\$(basename "\$u")"
  want="\$1"; shift
  got="\$(md5sum "\$f" | cut -d' ' -f1)"
  if [ "\$got" != "\$want" ]; then
    echo "MD5 mismatch on \$f: want \$want got \$got"
    echo MD5-MISMATCH > "$workroot/$prog.status"; exit 1
  fi
done

# 4. build non-interactively
chmod +x ./$prog.SlackBuild
if ! ./$prog.SlackBuild; then
  echo BUILD-FAILED > "$workroot/$prog.status"; exit 1
fi

# 5. installpkg the resulting package (written to the forced OUTPUT above)
out="\$OUTPUT"
pkg="\$(ls -t "\$out"/${prog}-*.t?z 2>/dev/null | head -n1)"
if [ -z "\$pkg" ]; then
  echo "No package produced in \$out"
  echo BUILD-FAILED > "$workroot/$prog.status"; exit 1
fi
if ! installpkg --terse "\$pkg"; then
  echo INSTALL-FAILED > "$workroot/$prog.status"; exit 1
fi
# Log the installed file list (from the package db) so the overlay is disposable.
echo "===== installed files: \$(basename "\$pkg") ====="
pkgname="\$(basename "\$pkg")"; pkgname="\${pkgname%.t?z}"
cat "/var/log/packages/\$pkgname" 2>/dev/null || echo "(package db entry not found: \$pkgname)"
echo "================================="
echo SUCCESS > "$workroot/$prog.status"
CHROOT_EOF

  local status="BUILD-FAILED"
  [[ -f "$statf" ]] && status="$(cat "$statf")"
  local end; end=$(date +%s)
  ST_TIME["$key"]=$(( end - start ))
  ST_STATUS["$key"]="$status"
  if [[ "$status" == "SUCCESS" ]]; then
    # Copy the produced package out of the overlay into the persistent cache
    # before teardown, so it can be reused as a dep in this or a later run. The
    # build wrote to the forced OUTPUT=/sbo-work/output (see the heredoc).
    local built newest=""
    for built in "$c"/sbo-work/output/${prog}-*.t?z; do
      [[ -e "$built" ]] || continue
      [[ -z "$newest" || "$built" -nt "$newest" ]] && newest="$built"
    done
    [[ -n "$newest" ]] && cache_store "$cat" "$prog" "$newest"
    return 0
  fi
  ST_REASON["$key"]="see $(basename "$logf")"
  return 1
}

# Echo a human label for a package's cache outcome, given its SlackBuild dir and
# whether it is the run's target. Mirrors cache_decision but renders text.
#   target, build (new) | target, rebuild: A -> B | cached (V) | rebuild: A -> B | build (new)
cache_label() {
  local dir="$1" is_target="$2"
  local cat prog ver dec
  cat="$(category_of "$dir")"; prog="$(basename "$dir")"; ver="$(version_of "$dir")"
  dec="$(cache_decision "$cat" "$prog" "$ver")"
  local label
  case "$dec" in
    cached)   label="cached ($ver)" ;;
    bump:*)   label="rebuild: ${dec#bump:}"; label="${label/:/ -> }" ;;
    *)        label="build (new)" ;;
  esac
  # The target always builds; never show it as plain "cached".
  if [[ "$is_target" == "1" ]]; then
    case "$dec" in
      cached) label="build (cached $ver, rebuilt as target)" ;;
    esac
    echo "target, $label"
  else
    echo "$label"
  fi
}

# =============================================================================
# Run one target: fresh overlay, build its resolved chain, teardown.
# Args: <target-slackbuild-dir>
# =============================================================================
run_target() {
  local target_dir="$1"
  local tkey; tkey="$(pkg_key "$target_dir")"

  echo
  echo "=== Target: $tkey ==="
  resolve_target "$target_dir"
  local resolve_rc=$?

  # Hard resolution failures: mark target and (newly seen) deps, skip building.
  if [[ ${#CYCLES[@]} -gt 0 || ${#UNMET[@]} -gt 0 ]]; then
    local why=""
    if [[ ${#UNMET[@]} -gt 0 ]]; then
      local u
      for u in "${!UNMET[@]}"; do why+="unmet:$u(${UNMET[$u]}) "; done
    fi
    [[ ${#CYCLES[@]} -gt 0 ]] && why+="${CYCLES[*]}"
    ST_STATUS["$tkey"]="UNMET-DEP"
    ST_REASON["$tkey"]="$why"
    echo "  resolution failed: $why"
    return
  fi

  if [[ $DRY_RUN -eq 1 ]]; then
    echo "  build order:"
    local d
    for d in "${RESOLVED_ORDER[@]}"; do
      local it=0; [[ "$d" == "$target_dir" ]] && it=1
      local rdm=""; [[ "${HAS_README[$d]:-}" == 1 ]] && rdm="  [%README%]"
      printf "    %-30s %s%s\n" "$(pkg_key "$d")" "$(cache_label "$d" "$it")" "$rdm"
      echo "$(pkg_key "$d")" >> "$RUN_DIR/build-order.txt"
    done
    return
  fi

  echo "  build order:"
  for d in "${RESOLVED_ORDER[@]}"; do
    local it=0; [[ "$d" == "$target_dir" ]] && it=1
    printf "    %-30s %s\n" "$(pkg_key "$d")" "$(cache_label "$d" "$it")"
    echo "$(pkg_key "$d")" >> "$RUN_DIR/build-order.txt"
  done

  local tmpdir; tmpdir="$(setup_overlay)"

  # Build chain in order. On a failure, mark dependents BLOCKED-BY-DEP.
  local d failed_progs=()
  for d in "${RESOLVED_ORDER[@]}"; do
    local key; key="$(pkg_key "$d")"
    local prog; prog="$(basename "$d")"

    # already blocked because an earlier dep it needs failed?
    if depends_on_failed "$d" failed_progs; then
      ST_STATUS["$key"]="BLOCKED-BY-DEP"
      ST_REASON["$key"]="blocked by failed dep"
      [[ "${HAS_README[$d]:-}" == "1" ]] && ST_README["$key"]=1
      echo "  $key: BLOCKED-BY-DEP"
      failed_progs+=("$prog")
      continue
    fi

    local it=0; [[ "$d" == "$target_dir" ]] && it=1
    echo "  building $key ..."
    if build_one "$tmpdir" "$d" "$it"; then
      echo "  $key: ${ST_STATUS[$key]} (${ST_TIME[$key]}s)"
    else
      echo "  $key: ${ST_STATUS[$key]} (${ST_TIME[$key]}s)"
      failed_progs+=("$prog")
    fi
  done

  # Overlay is always torn down: the per-package logs capture everything worth
  # inspecting (full build/install output, resolved .info env, installed file
  # list), so there is no reason to retain the filesystem.
  teardown_overlay "$tmpdir"
}

# Does SlackBuild dir $1 directly require any prog in failed list (nameref $2)?
# ponytail: direct REQUIRES check only; transitive blocking still works because
# this runs in topo order, so a dep's failure propagates up one hop at a time.
depends_on_failed() {
  local dir="$1"; local -n failed="$2"
  local info="$dir/$(basename "$dir").info"
  local req tok f
  req="$(read_requires "$info")"
  for tok in $req; do
    [[ "$tok" == "%README%" ]] && continue
    for f in "${failed[@]:-}"; do
      [[ "$tok" == "$f" ]] && return 0
    done
  done
  return 1
}

# =============================================================================
# SUMMARY (screen color + plain summary.log)
# =============================================================================
print_summary() {
  local total=$SECONDS
  local succ=0 fail=0 blocked=0 cached=0
  local summary="$RUN_DIR/summary.log"

  {
    echo "sbo-batch-test run summary"
    echo "target: $TARGET_ARG"
    echo
  } > "$summary"

  echo
  echo "================ SUMMARY ================"
  local key
  for key in "${!ST_STATUS[@]}"; do
    local st="${ST_STATUS[$key]}" rsn="${ST_REASON[$key]:-}" t="${ST_TIME[$key]:-0}"
    local rd=""; [[ "${ST_README[$key]:-}" == "1" ]] && rd=" [%README%]"
    local col="$C_YEL"
    case "$st" in
      SUCCESS) col="$C_GRN"; ((succ++)) ;;
      CACHED)  col="$C_GRN"; ((cached++)) ;;
      BLOCKED-BY-DEP|UNMET-DEP) col="$C_YEL"; ((blocked++)) ;;
      *) col="$C_RED"; ((fail++)) ;;
    esac
    printf "%s%-30s %-16s%s %s%s (%ss)\n" "$col" "$key" "$st" "$C_RST" "$rsn" "$rd" "$t"
    printf "%-30s %-16s %s%s (%ss)\n" "$key" "$st" "$rsn" "$rd" "$t" >> "$summary"
  done
  echo "----------------------------------------"
  printf "%s%d succeeded%s, %s%d failed%s, %s%d blocked%s, %s%d cached%s, total %ss\n" \
    "$C_GRN" "$succ" "$C_RST" "$C_RED" "$fail" "$C_RST" "$C_YEL" "$blocked" "$C_RST" \
    "$C_GRN" "$cached" "$C_RST" "$total"
  echo "logs: $RUN_DIR"
  {
    echo
    echo "$succ succeeded, $fail failed, $blocked blocked, $cached cached, total ${total}s"
    echo "logs: $RUN_DIR"
  } >> "$summary"
}

# =============================================================================
# main
# =============================================================================
main() {
  parse_args "$@"
  init_color
  if [[ $INIT_BASE -eq 1 ]]; then
    init_base
    exit 0
  fi
  validate_env

  RUN_DIR="$LOG_ROOT/$(date +%Y-%m-%d_%H-%M-%S)"
  mkdir -p "$RUN_DIR"
  : > "$RUN_DIR/build-order.txt"

  [[ $DRY_RUN -eq 0 ]] && update_base

  [[ $WITH_X -eq 1 ]] && { echo "X passthrough on (xhost +local:hosts). Security: allows local connections to your X server."; xhost +local:hosts >/dev/null; }

  # Collect targets.
  local -a targets=()
  if [[ -d "$TARGET_ARG" ]]; then
    # category-folder mode: every subdir with a matching .info is a target
    local d prog
    for d in "$TARGET_ARG"/*; do
      [[ -d "$d" ]] || continue
      prog="$(basename "$d")"
      [[ -f "$d/$prog.info" ]] && targets+=("$d")
    done
    if [[ ${#targets[@]} -eq 0 ]]; then
      echo "No SlackBuild targets found in folder: $TARGET_ARG" >&2
      exit 1
    fi
  else
    # single-package mode: resolve the name in the tree
    local tdir
    if tdir="$(find_slackbuild_dir "$TARGET_ARG")"; then
      targets+=("$tdir")
    else
      echo "Program not found in any SBo tree root: $TARGET_ARG" >&2
      exit 1
    fi
  fi

  # TODO: "all" mode and queue/list-file mode plug in here (populate `targets`).

  local t
  for t in "${targets[@]}"; do
    run_target "$t"
  done

  print_summary
}

main "$@"
