kampodine 0.4.0 → 0.6.0

package/scripts/common.sh

@@ -0,0 +1,644 @@
+#!/usr/bin/env bash
+# common.sh — shared library for the deployment lifecycle: the local
+# append-only deployment ledger (~/.kampodine/deployments.jsonl), the disk
+# guard math, the prune keep-set selection, and the deploy-list rendering.
+#
+# Sourced by deploy.sh, deploy-lifecycle.sh, and status.sh. Defines functions
+# ONLY — no side effects at source time, no option changes, no output.
+#
+# Everything here runs on the DEPLOY MACHINE (bash, macOS or Linux); the
+# busybox constraint applies to the remote command strings the callers
+# compose, not to this file.
+#
+# Ledger contract (the deployment HISTORY — the owner's source of truth):
+#   {"ts":"…","host":"…","sha":"…","tag":"…","result":"…","duration_ms":N,"subject":"…"}
+# One fixed key order, values JSON-escaped; shas/tags/hosts/subjects only —
+# NEVER secrets, env payloads, or key paths. Readers rely on the fixed order
+# and on escaped values (no unescaped '"' inside strings), so fixed-string
+# grep and field splitting are exact.
+
+LEDGER_DIR_NAME=".kampodine"
+LEDGER_FILE_NAME="deployments.jsonl"
+# Named tags the prune keep-set never touches. The sha-tag filter already
+# excludes them from candidates; listed here so the rule is explicit.
+PRUNE_KEEP_TAGS="latest ts-rollback"
+
+# --- ledger -------------------------------------------------------------------
+
+# ledger_dir -> prints ~/.kampodine, creating it 0700 if missing.
+ledger_dir() {
+  local dir="${HOME:?kampodine ledger requires HOME}/${LEDGER_DIR_NAME}"
+  mkdir -p "$dir" 2>/dev/null || true
+  chmod 700 "$dir" 2>/dev/null || true
+  printf '%s' "$dir"
+}
+
+# ledger_file -> prints the ledger's full path (dir is created 0700).
+ledger_file() {
+  printf '%s/%s' "$(ledger_dir)" "$LEDGER_FILE_NAME"
+}
+
+# json_escape_str "$s" -> stdout: $s escaped for a JSON string literal
+# (backslash, double quote, tab/newline/CR flattened to spaces — subjects
+# are single-line by construction).
+json_escape_str() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\t'/ }"
+  s="${s//$'\n'/ }"
+  s="${s//$'\r'/ }"
+  printf '%s' "$s"
+}
+
+# ledger_append <host> <sha> <tag> <result> <duration_ms> [subject]
+# Appends ONE JSONL line. Validates every field and refuses to write on any
+# violation (a malformed line would poison every reader — the ledger is
+# append-only, there is no repair). Returns 1 without writing on invalid
+# input; the caller decides whether that is fatal.
+ledger_append() {
+  local host="$1" sha="$2" tag="$3" result="$4" duration_ms="$5" subject="${6:-}"
+  [[ -n "$host" && "$host" =~ ^[^[:space:]]+$ ]] || return 1
+  [[ "$sha" =~ ^[0-9a-f]{4,40}$ ]] || return 1
+  [[ "$tag" =~ ^[0-9a-f]{4,40}$ ]] || return 1
+  case "$result" in
+    success|failed|rollback) ;;
+    *) return 1 ;;
+  esac
+  [[ "$duration_ms" =~ ^[0-9]+$ ]] || return 1
+  local ts file
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  file="$(ledger_file)"
+  # 0600 from creation: umask 077 around the append (the file is local state,
+  # but hosts+subjects are not everyone's business).
+  umask 077
+  printf '{"ts":"%s","host":"%s","sha":"%s","tag":"%s","result":"%s","duration_ms":%s,"subject":"%s"}\n' \
+    "$ts" "$(json_escape_str "$host")" "$sha" "$tag" "$result" "$duration_ms" \
+    "$(json_escape_str "$subject")" >> "$file" || return 1
+  chmod 600 "$file" 2>/dev/null || true
+}
+
+# ledger_entries [host] -> prints matching JSONL lines (all hosts when no
+# host given; empty output when the ledger does not exist yet).
+# Host matching is a FIXED-STRING match on the `"host":"…","sha":"` seam:
+# the fixed key order + JSON escaping guarantee this byte sequence can only
+# be the field itself, never a forged occurrence inside a value.
+ledger_entries() {
+  local file
+  file="$(ledger_file)"
+  [[ -f "$file" ]] || return 0
+  if [[ $# -ge 1 && -n "$1" ]]; then
+    grep -F "\"host\":\"$1\",\"sha\":\"" "$file" 2>/dev/null || true
+  else
+    cat "$file" 2>/dev/null || true
+  fi
+}
+
+# ledger_count [host] -> prints the number of ledger entries.
+ledger_count() {
+  local n
+  n="$(ledger_entries "${1:-}" | grep -c . || true)"
+  printf '%s' "${n:-0}"
+}
+
+# extract_ledger_field <jsonl-line> <field-name> -> prints the field's value
+# (quotes stripped for string fields; numbers pass through). Relies on the
+# fixed key order: split on the `,"` seam — every key after the first is
+# preceded by comma-quote, and the escaping guarantees a value can never
+# contain an unescaped `,"` (in-value quotes are backslash-escaped), so the
+# split is exact even across the unquoted duration_ms number. POSIX awk only —
+# this runs on macOS too.
+extract_ledger_field() {
+  awk -F',"' -v want="$2" '{
+    gsub(/^\{/, ""); gsub(/\}$/, "")
+    for (i = 1; i <= NF; i++) {
+      key = $i; sub(/:.*/, "", key); gsub(/^"/, "", key); gsub(/"$/, "", key)
+      if (key == want) {
+        val = $i; sub(/^[^:]*:/, "", val); gsub(/^"/, "", val); gsub(/"$/, "", val)
+        print val
+        exit
+      }
+    }
+  }' <<<"$1"
+}
+
+# ledger_subject_for_tag <host> <tag> -> prints the NEWEST recorded subject
+# for that host+tag (used to re-attach history to a rollback), empty if none.
+ledger_subject_for_tag() {
+  local line
+  line="$(ledger_entries "$1" | grep -F "\"tag\":\"$2\",\"result\"" | tail -n 1 || true)"
+  [[ -n "$line" ]] || return 0
+  extract_ledger_field "$line" subject
+}
+
+# ledger_total_line <count> [note] -> prints the owner-visible footer line.
+ledger_total_line() {
+  printf 'Total deployments: %s%s\n' "$1" "${2:+ · $2}"
+}
+
+# --- disk guard ----------------------------------------------------------------
+
+# disk_pct_from_df "<df -P output>" -> prints the usage percentage (integer)
+# from the last data line's Capacity/Use% column, or nothing when the input
+# is not df output. POSIX: `df -P` puts the percentage in field 5 on both
+# BSD and GNU.
+disk_pct_from_df() {
+  printf '%s\n' "$1" | awk 'NF >= 5 { pct = $5 } END { if (pct ~ /%$/) { sub(/%$/, "", pct); print pct } }'
+}
+
+# disk_verdict <pct|empty> <require-pct|empty> -> prints one of:
+#   fail    usage >= require-pct        (the --require-disk fail-closed gate)
+#   warn    usage > 90                  (the always-on loud warning)
+#   ok      otherwise
+#   unknown pct missing/unparseable     (callers decide if that is fatal)
+disk_verdict() {
+  local pct="$1" require="$2"
+  if [[ -z "$pct" || ! "$pct" =~ ^[0-9]+$ ]]; then
+    printf 'unknown'
+    return 0
+  fi
+  if [[ -n "$require" && "$require" =~ ^[0-9]+$ && "$pct" -ge "$require" ]]; then
+    printf 'fail'
+    return 0
+  fi
+  if [[ "$pct" -gt 90 ]]; then
+    printf 'warn'
+    return 0
+  fi
+  printf 'ok'
+}
+
+# --- prune keep-set --------------------------------------------------------------
+
+# running_tags_from_ps "<podman ps --format {{.Image}} output>" -> prints ONE
+# space-padded line of bare tags (" tag1 tag2 "), ready for *" tag "* case
+# matches. Digest refs (repo@sha256:…) carry no tag and are skipped; unrelated
+# repos simply contribute their tag.
+running_tags_from_ps() {
+  local r out=""
+  while IFS= read -r r; do
+    [[ -n "$r" ]] || continue
+    case "$r" in *@*) continue ;; esac
+    case "$r" in *:*) out+=" ${r##*:} " ;; esac
+  done <<<"$1"
+  printf '%s' "$out"
+}
+
+# sha_tagged_lines "<images listing>" -> filters "tag|created|size" lines to
+# sha-like tags. This single rule is what keeps latest / ts-rollback / <none>
+# out of every removal candidate.
+sha_tagged_lines() {
+  local line tag
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    tag="${line%%|*}"
+    [[ "$tag" =~ ^[0-9a-f]{7,40}$ ]] || continue
+    printf '%s\n' "$line"
+  done <<<"$1"
+}
+
+# prune_select "<images listing>" "<ps image lines>" <keep_n>
+#   images listing: "tag|CreatedAt|Size" lines for the deploy image repository
+#   stdout: removal lines "tag|size" (empty = nothing to remove)
+# ALWAYS kept: the running image(s), ts-rollback + latest (named keeps), and
+# the newest keep_n sha-tags by creation timestamp. `podman rmi` on a shared
+# ID only strips the tag — but the running image is excluded regardless, so
+# nothing a container is using is ever proposed.
+prune_select() {
+  local images="$1" running="$2" keep_n="$3" keep_newest line tag size
+  [[ "$keep_n" =~ ^[0-9]+$ ]] || return 1
+
+  local running_tags
+  running_tags="$(running_tags_from_ps "$running")"
+
+  local candidates
+  candidates="$(sha_tagged_lines "$images")"
+  [[ -n "$candidates" ]] || return 0
+
+  # BSD head rejects -n 0 — an empty keep_newest means "keep none"
+  keep_newest=""
+  if [[ "$keep_n" -gt 0 ]]; then
+    keep_newest="$(printf '%s\n' "$candidates" | sort -t'|' -k2,2r | head -n "$keep_n" | cut -d'|' -f1)"
+  fi
+
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    tag="${line%%|*}"
+    size="$(printf '%s' "$line" | cut -d'|' -f3)"
+    case "$PRUNE_KEEP_TAGS" in *" $tag "*) continue ;; esac
+    case "$running_tags" in *" $tag "*) continue ;; esac
+    if printf '%s\n' "$keep_newest" | grep -Fxq "$tag"; then continue; fi
+    printf '%s|%s\n' "$tag" "$size"
+  done <<<"$candidates"
+}
+
+# sum_sizes_human "<size lines like '936 MB'>" -> prints one human estimate
+# ("~1.8 GB", "~512 MB", "~0 MB"). Approximate by design — it labels itself
+# with ~ and exists to size the prune reward, not for accounting.
+sum_sizes_human() {
+  printf '%s\n' "$1" | awk '
+    {
+      v = $1 + 0; u = toupper($2)
+      if (u == "GB") t += v * 1024
+      else if (u == "MB") t += v
+      else if (u == "KB") t += v / 1024
+    }
+    END {
+      if (t >= 1024) printf "~%.1f GB", t / 1024
+      else if (t >= 1) printf "~%d MB", t
+      else printf "~0 MB"
+    }'
+}
+
+# --- deploy list rendering -------------------------------------------------------
+
+# render_deploy_list "<images listing>" "<ps image lines>" "<ledger lines>"
+# -> prints table ROWS (no header/footer): VM sha-tagged rows newest-first,
+# then ledger-only rows (tags pruned on the VM, or deployed from elsewhere /
+# failed before load). The running tag is marked; ledger entries enrich each
+# row with the last result + recorded subject.
+render_deploy_list() {
+  local images="$1" running="$2" ledger="$3"
+  local running_tags vm_tags line tag created state result subject lline
+  running_tags="$(running_tags_from_ps "$running")"
+  vm_tags=" "
+
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    tag="${line%%|*}"
+    created="$(printf '%s' "$line" | cut -d'|' -f2)"
+    state="on VM"
+    case "$running_tags" in *" $tag "*) state="RUNNING" ;; esac
+    result="-"
+    subject="-"
+    lline="$(printf '%s\n' "$ledger" | grep -F "\"tag\":\"$tag\",\"result\"" | tail -n 1 || true)"
+    if [[ -n "$lline" ]]; then
+      result="$(extract_ledger_field "$lline" result)"
+      subject="$(extract_ledger_field "$lline" subject)"
+      [[ -n "$subject" ]] || subject="-"
+    fi
+    printf '%-9s %-17s %-9s %-9s %s\n' "$tag" "${created:0:16}" "$state" "$result" "$subject"
+    vm_tags+=" $tag "
+  done <<<"$(printf '%s\n' "$images" | sed '/^$/d' | sort -t'|' -k2,2r)"
+
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    tag="$(extract_ledger_field "$line" tag)"
+    [[ "$tag" =~ ^[0-9a-f]{7,40}$ ]] || continue
+    case "$vm_tags" in *" $tag "*) continue ;; esac
+    result="$(extract_ledger_field "$line" result)"
+    subject="$(extract_ledger_field "$line" subject)"
+    printf '%-9s %-17s %-9s %-9s %s\n' "$tag" "$(extract_ledger_field "$line" ts)" \
+      "not on VM" "$result" "${subject:--}"
+  done <<<"$ledger"
+}
+
+# --- profiles (~/.kampodine/config.json) ----------------------------------------
+#
+# Per-instance config, FLAT by owner decision: each profile carries
+# host/sshKey/proxyHost/group — NO inheritance between profiles (the schema
+# only LEAVES ROOM for a future "defaults" block; nothing reads one here).
+# `group` is cosmetic: config list --group filters, nothing else consumes it.
+# The file never holds secrets — sshKey is a PATH.
+#
+# Resolution everywhere (profile_resolve, called once per script AFTER flag
+# parsing): explicit flag > env (KAMPODINE_PROFILE) > defaultProfile from
+# config > the script's legacy behavior. A resolved profile's host/sshKey
+# override KAMPODINE_HOST/KAMPODINE_SSH_KEY only when no explicit flag was
+# passed — per-invocation always beats per-instance.
+
+CONFIG_FILE_NAME="config.json"
+
+# config_file -> prints ~/.kampodine/config.json (dir created 0700 if needed).
+config_file() {
+  printf '%s/%s' "$(ledger_dir)" "$CONFIG_FILE_NAME"
+}
+
+# is_profile_name <name> -> 0 when the name is config-key safe.
+is_profile_name() {
+  [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$ ]]
+}
+
+# config_require_jq -> 0 when jq exists (config reads/rewrites are jq-only;
+# machines without a config never need it).
+config_require_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    printf '[kampodine] FAIL: jq is required to read %s — install jq (brew install jq)\n' "$(config_file)" >&2
+    return 1
+  }
+}
+
+# config_default_profile -> prints defaultProfile ("" when no config yet).
+config_default_profile() {
+  local f
+  f="$(config_file)"
+  [[ -f "$f" ]] || return 0
+  config_require_jq || return 1
+  jq -r '.defaultProfile // empty' "$f" 2>/dev/null || return 1
+}
+
+# config_profile_names -> newline-separated profile names ("" without config).
+config_profile_names() {
+  local f
+  f="$(config_file)"
+  [[ -f "$f" ]] || return 0
+  config_require_jq || return 1
+  jq -r '.profiles // {} | keys[]' "$f" 2>/dev/null || return 1
+}
+
+# profile_field <name> <field> -> prints the field value ("" when the field
+# is unset); fails when the profile is unknown, naming the known set.
+profile_field() {
+  local name="$1" field="$2" f
+  f="$(config_file)"
+  [[ -f "$f" ]] || {
+    printf '[kampodine] FAIL: no profile config at %s — known profiles: (none — create one: kampodine config init --name <name> --host root@<ip>)\n' "$f" >&2
+    return 1
+  }
+  config_require_jq || return 1
+  if [[ "$(jq -r --arg n "$name" '.profiles // {} | has($n)' "$f" 2>/dev/null)" != "true" ]]; then
+    printf '[kampodine] FAIL: unknown profile "%s" — known: %s (see: kampodine config list)\n' \
+      "$name" "$(config_profile_names | paste -sd' ' -)" >&2
+    return 1
+  fi
+  jq -r --arg n "$name" --arg k "$field" '.profiles[$n][$k] // empty' "$f" 2>/dev/null
+}
+
+# profile_resolve [explicit-profile] [host-flag] [ssh-key-flag]
+# ONE call gives every script profile awareness. Effects:
+#   sets PROFILE_NAME / PROFILE_GROUP / PROFILE_HOST / PROFILE_SSH_KEY /
+#   PROFILE_PROXY_HOST (all "" when nothing resolves)
+#   overrides KAMPODINE_HOST / KAMPODINE_SSH_KEY from the profile ONLY when
+#   the corresponding explicit flag is absent — an explicit per-invocation
+#   flag always wins, the profile beats the legacy env it replaces.
+# Selection: $1 > KAMPODINE_PROFILE > config defaultProfile.
+# shellcheck disable=SC2034  # PROFILE_* / KAMPODINE_* are consumed by callers
+profile_resolve() {
+  PROFILE_NAME="" PROFILE_GROUP="" PROFILE_HOST="" PROFILE_SSH_KEY="" PROFILE_PROXY_HOST=""
+  local explicit="${1:-}" host_flag="${2:-}" key_flag="${3:-}" name=""
+  if [[ -n "$explicit" ]]; then
+    name="$explicit"
+  elif [[ -n "${KAMPODINE_PROFILE:-}" ]]; then
+    name="$KAMPODINE_PROFILE"
+  else
+    name="$(config_default_profile)" || return 1
+  fi
+  [[ -z "$name" ]] && return 0
+  # validates existence (dies with the known set when unknown)
+  PROFILE_HOST="$(profile_field "$name" host)"
+  PROFILE_NAME="$name"
+  PROFILE_GROUP="$(profile_field "$name" group)"
+  PROFILE_SSH_KEY="$(profile_field "$name" sshKey)"
+  PROFILE_PROXY_HOST="$(profile_field "$name" proxyHost)"
+  if [[ -z "$host_flag" && -n "$PROFILE_HOST" ]]; then
+    KAMPODINE_HOST="$PROFILE_HOST"
+  fi
+  if [[ -z "$key_flag" && -n "$PROFILE_SSH_KEY" ]]; then
+    KAMPODINE_SSH_KEY="$PROFILE_SSH_KEY"
+  fi
+  return 0
+}
+
+# --- host init detection (groundwork for non-Alpine targets) ---------------------
+#
+# Detection + action resolution ONLY — no per-OS bootstrap lives here.
+# On first connect init_detect probes the host once: rc-service (OpenRC/
+# Alpine) vs systemctl (systemd) vs neither, and piggybacks an http-client
+# probe (busybox wget stays the default; curl is the GNU-only-host fallback).
+# The init verdict is cached in the active profile entry ("init" field) so
+# later runs skip the probe; without a profile it is a per-process cache.
+
+INIT_SYSTEM=""
+REMOTE_HTTP_CLIENT=""
+
+# init_detect <run-fn> -> prints the init verdict ("" when none detected).
+# <run-fn> is the script's remote-run wrapper (e.g. vm), called with ONE
+# composed probe command. Order matters: a cached profile verdict
+# short-circuits the probe entirely (one round-trip ever, per host).
+init_detect() {
+  local run_fn="$1" out init httpc
+  if [[ -z "$INIT_SYSTEM" && -n "$PROFILE_NAME" ]]; then
+    INIT_SYSTEM="$(profile_field "$PROFILE_NAME" init)"
+  fi
+  if [[ -n "$INIT_SYSTEM" ]]; then
+    printf '%s' "$INIT_SYSTEM"
+    return 0
+  fi
+  out="$("$run_fn" 'if command -v rc-service >/dev/null 2>&1; then echo openrc; elif command -v systemctl >/dev/null 2>&1; then echo systemd; else echo none; fi; if command -v wget >/dev/null 2>&1; then echo httpc=wget; elif command -v curl >/dev/null 2>&1; then echo httpc=curl; else echo httpc=none; fi' 2>/dev/null)" || out=""
+  init="$(printf '%s\n' "$out" | awk 'NR == 1 { print $1 }')"
+  httpc="$(printf '%s\n' "$out" | awk -F= '$1 == "httpc" { print $2 }')"
+  case "$init" in
+    openrc|systemd) INIT_SYSTEM="$init" ;;
+    *) INIT_SYSTEM="" ;;
+  esac
+  case "$httpc" in
+    wget|curl) REMOTE_HTTP_CLIENT="$httpc" ;;
+    *) REMOTE_HTTP_CLIENT="" ;;
+  esac
+  # best-effort cache: only with an active profile (the profile IS the host
+  # binding); never fatal — jq-less machines still get working detection.
+  if [[ -n "$PROFILE_NAME" && -n "$INIT_SYSTEM" ]]; then
+    config_set_profile_field "$PROFILE_NAME" init "$INIT_SYSTEM" 2>/dev/null || true
+  fi
+  printf '%s' "$INIT_SYSTEM"
+}
+
+# svc_action <service> <start|stop|restart> -> prints the remote command for
+# the detected init system. OpenRC output is byte-identical to the historical
+# strings; fails (rc != 0, no output) when no init was detected — callers
+# decide whether that is fatal (restart: yes, diagnostics: no).
+svc_action() {
+  local svc="$1" action="$2"
+  case "$INIT_SYSTEM" in
+    openrc)  printf 'rc-service %s %s' "$svc" "$action" ;;
+    systemd) printf 'systemctl %s %s' "$action" "$svc" ;;
+    *) return 1 ;;
+  esac
+}
+
+# config_set_profile_field <name> <field> <value> — best-effort profile cache
+# write (atomic 0600; requires jq; fails quietly on missing config).
+config_set_profile_field() {
+  local name="$1" field="$2" value="$3" f tmp new
+  f="$(config_file)"
+  [[ -f "$f" ]] || return 1
+  config_require_jq || return 1
+  new="$(jq --arg n "$name" --arg k "$field" --arg v "$value" \
+    '.profiles[$n][$k] = $v' "$f" 2>/dev/null)" || return 1
+  tmp="$f.tmp.$$"
+  umask 077
+  printf '%s\n' "$new" > "$tmp" && chmod 600 "$tmp" && mv -f "$tmp" "$f"
+}
+
+# remote_http_cmd <url> -> the remote fetch command for the host's http
+# client. busybox wget is the DEFAULT (byte-identical historical health
+# probe); curl is the fallback for GNU-only hosts (no wget).
+remote_http_cmd() {
+  case "$REMOTE_HTTP_CLIENT" in
+    curl) printf 'curl -s -m 3 %s 2>/dev/null' "$1" ;;
+    *)    printf 'wget -qO- -T 3 %s 2>/dev/null' "$1" ;;
+  esac
+}
+
+# --- metrics snapshot -------------------------------------------------------------
+#
+# ONE SSH round-trip captures every section (busybox-safe remote commands
+# only: cat/echo/nproc/df/du/podman/ps/sort/head); parsing + rendering are
+# client-side pure functions below. metrics.sh renders this for `kampodine
+# metrics`; status.sh folds the SAME snapshot in behind --verbose.
+
+# shellcheck disable=SC2034  # consumed by metrics.sh / status.sh
+METRICS_REMOTE_CMD="echo '%%KAMPODINE:LOAD%%'; cat /proc/loadavg 2>/dev/null; echo '%%KAMPODINE:CPU%%'; nproc 2>/dev/null; echo '%%KAMPODINE:MEM%%'; cat /proc/meminfo 2>/dev/null; echo '%%KAMPODINE:UPTIME%%'; cat /proc/uptime 2>/dev/null; echo '%%KAMPODINE:DISK%%'; df -P / 2>/dev/null; echo '%%KAMPODINE:DU%%'; du -sm /var/lib/containers /data 2>/dev/null; echo '%%KAMPODINE:PODMAN%%'; podman stats --no-stream --format '{{.Name}}|{{.CPUPerc}}|{{.MemUsage}}' 2>/dev/null; echo '%%KAMPODINE:TOP%%'; ps aux 2>/dev/null | grep -v '^USER' | sort -k6 -rn | head -n 5; echo '%%KAMPODINE:END%%'"
+
+# metrics_uptime_human "<proc/uptime line>" -> "12d 2h 36m" ("" when absent).
+metrics_uptime_human() {
+  local secs
+  secs="$(printf '%s' "$1" | awk '{print int($1)}')"
+  [[ "$secs" =~ ^[0-9]+$ ]] || return 0
+  awk -v s="$secs" 'BEGIN {
+    d = int(s / 86400); s -= d * 86400
+    h = int(s / 3600);  s -= h * 3600
+    m = int(s / 60)
+    if (d > 0) printf "%dd %dh %dm", d, h, m
+    else if (h > 0) printf "%dh %dm", h, m
+    else printf "%dm", m
+  }'
+}
+
+# metrics_load_line "<loadavg line>" <nproc> -> "0.52 0.58 0.59 (4 CPUs)".
+metrics_load_line() {
+  local avg cpus
+  avg="$(printf '%s' "$1" | awk '{print $1, $2, $3}')"
+  cpus="${2//[!0-9]/}"
+  if [[ -z "${avg//[[:space:]]/}" ]]; then
+    printf 'load unreadable'
+    return 0
+  fi
+  [[ -n "$cpus" ]] || cpus="?"
+  printf '%s (%s CPUs)' "$avg" "$cpus"
+}
+
+# metrics_mem_usage "<meminfo text>" -> "used N MiB · avail N MiB · total N MiB".
+# Available prefers MemAvailable; falls back to MemFree+Buffers+Cached.
+metrics_mem_usage() {
+  printf '%s\n' "$1" | awk '
+    $1 == "MemTotal:" { t = $2 }
+    $1 == "MemAvailable:" { a = $2 }
+    $1 == "MemFree:" { f = $2 }
+    $1 == "Buffers:" { b = $2 }
+    $1 == "Cached:" { c = $2 }
+    END {
+      if (t == "") t = 0
+      if (a == "") a = f + b + c
+      total = int(t / 1024); avail = int(a / 1024); used = total - avail
+      if (used < 0) used = 0
+      printf "used %d MiB · avail %d MiB · total %d MiB", used, avail, total
+    }'
+}
+
+# metrics_disk_breakdown "<df / output>" "<du -sm output>" -> four lines:
+# the root usage line (disk_pct_from_df) + images/data/other. "other" is the
+# df used MiB minus the two du readings, floored at 0 (du and df disagree by
+# design; this is a CLI triage view, not accounting).
+metrics_disk_breakdown() {
+  local pct images data used_mb other
+  pct="$(disk_pct_from_df "$1")"
+  if [[ -n "$pct" ]]; then
+    printf 'disk /    : %s%% used\n' "$pct"
+  else
+    printf 'disk /    : unknown (df unreadable)\n'
+  fi
+  images="$(printf '%s\n' "$2" | awk '$2 == "/var/lib/containers" { print $1 }')"
+  data="$(printf '%s\n' "$2" | awk '$2 == "/data" { print $1 }')"
+  used_mb="$(printf '%s\n' "$1" | awk 'NF >= 6 { u = $3 } END { if (u != "") print int(u / 1024) }')"
+  other=0
+  if [[ -n "$used_mb" ]]; then
+    other=$(( used_mb - ${images:-0} - ${data:-0} ))
+    (( other < 0 )) && other=0
+  fi
+  printf '  images  : %s MB (/var/lib/containers)\n' "${images:-?}"
+  printf '  data    : %s MB (/data)\n' "${data:-0}"
+  if [[ -n "$used_mb" ]]; then
+    printf '  other   : %s MB (est.)\n' "$other"
+  else
+    printf '  other   : unknown (df unreadable)\n'
+  fi
+}
+
+# metrics_containers_lines "<podman stats name|cpu|mem lines>" -> table rows;
+# empty input prints an honest "(no containers…)" line.
+metrics_containers_lines() {
+  if [[ -z "${1//[[:space:]]/}" ]]; then
+    printf '  (no containers or podman unreachable)\n'
+    return 0
+  fi
+  local line name cpu mem
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    name="${line%%|*}"; line="${line#*|}"
+    cpu="${line%%|*}"; mem="${line#*|}"
+    printf '  %-22s %-8s %s\n' "$name" "$cpu" "$mem"
+  done <<<"$1"
+}
+
+# metrics_top_procs "<ps aux output, sorted by RSS>" -> at most 5 rows,
+# header dropped (client-side cap; the remote command pre-sorts + pre-caps).
+metrics_top_procs() {
+  local line n=0
+  while IFS= read -r line; do
+    [[ -n "$line" ]] || continue
+    case "$line" in USER\ *|%\ CPU*) continue ;; esac
+    printf '%s\n' "$line" | awk '{
+      user = $1; rss = $6
+      cmd = ""
+      if (NF >= 11) { for (i = 11; i <= NF; i++) cmd = cmd (i > 11 ? " " : "") $i }
+      else if (NF >= 9) { for (i = 9; i <= NF; i++) cmd = cmd (i > 9 ? " " : "") $i }
+      else cmd = $0
+      printf "  %8d KB  %-8s %s\n", rss, user, cmd
+    }'
+    n=$(( n + 1 ))
+    (( n >= 5 )) && return 0
+  done <<<"$1"
+}
+
+# metrics_render "<raw snapshot>" -> prints the full snapshot block (no
+# heading — the caller owns it). Also leaves the per-section buffers in the
+# M_* globals (M_DISK is what the --warn-disk threshold re-reads).
+# shellcheck disable=SC2034  # M_* buffers are consumed by callers
+metrics_render() {
+  local raw="$1" line
+  M_LOAD="" M_CPU="" M_MEM="" M_UPTIME="" M_DISK="" M_DU="" M_PODMAN="" M_TOP=""
+  while IFS= read -r line; do
+    case "$line" in
+      "%%KAMPODINE:LOAD%%")   section="load" ;;
+      "%%KAMPODINE:CPU%%")    section="cpu" ;;
+      "%%KAMPODINE:MEM%%")    section="mem" ;;
+      "%%KAMPODINE:UPTIME%%") section="uptime" ;;
+      "%%KAMPODINE:DISK%%")   section="disk" ;;
+      "%%KAMPODINE:DU%%")     section="du" ;;
+      "%%KAMPODINE:PODMAN%%") section="podman" ;;
+      "%%KAMPODINE:TOP%%")    section="top" ;;
+      "%%KAMPODINE:"*"%%")    section="" ;;
+      *)
+        case "${section:-}" in
+          load)   M_LOAD+="$line"$'\n' ;;
+          cpu)    M_CPU+="$line"$'\n' ;;
+          mem)    M_MEM+="$line"$'\n' ;;
+          uptime) M_UPTIME+="$line"$'\n' ;;
+          disk)   M_DISK+="$line"$'\n' ;;
+          du)     M_DU+="$line"$'\n' ;;
+          podman) M_PODMAN+="$line"$'\n' ;;
+          top)    M_TOP+="$line"$'\n' ;;
+        esac
+        ;;
+    esac
+  done <<<"$raw"
+  printf 'uptime    : %s\n' "$(metrics_uptime_human "$M_UPTIME")"
+  printf 'load      : %s\n' "$(metrics_load_line "$M_LOAD" "$M_CPU")"
+  printf 'memory    : %s\n' "$(metrics_mem_usage "$M_MEM")"
+  metrics_disk_breakdown "$M_DISK" "$M_DU"
+  printf 'containers:\n'
+  metrics_containers_lines "$M_PODMAN"
+  printf 'top rss   :\n'
+  metrics_top_procs "$M_TOP"
+}